CD BIT 75/CD BIT 75.iso/Software/mysql-4.0.22-win/data1.cab/Documentation/Docs/manual.txt

Text File | 2004-10-28 | 3.8 MB | 96,485 lines

START-INFO-DIR-ENTRY
* mysql: (mysql).               MySQL documentation.
END-INFO-DIR-ENTRY

Table of Contents
*****************


General Information
  About This Manual
    Conventions Used in This Manual
  Overview of the MySQL Database Management System
    History of MySQL
    The Main Features of MySQL
    MySQL Stability
    How Big MySQL Tables Can Be
    Year 2000 Compliance
  Overview of MySQL AB
    The Business Model and Services of MySQL AB
      Support
      Training and Certification
      Consulting
      Commercial Licenses
      Partnering
    Contact Information
  MySQL Support and Licensing
    Support Offered by MySQL AB
    Copyrights and Licenses Used by MySQL
    MySQL Licenses
      Using the MySQL Software Under a Commercial License
      Using the MySQL Software for Free Under GPL
    MySQL AB Logos and Trademarks
      The Original MySQL Logo
      MySQL Logos That May Be Used Without Written Permission
      When You Need Written Permission to Use MySQL Logos
      MySQL AB Partnership Logos
      Using the Word MySQL in Printed Text or Presentations
      Using the Word MySQL in Company and Product Names
  MySQL Development Roadmap
    MySQL 4.0 in a Nutshell
      Features Available in MySQL 4.0
      The Embedded MySQL Server
    MySQL 4.1 in a Nutshell
      Features Available in MySQL 4.1
      Stepwise Rollout
      Ready for Immediate Development Use
    MySQL 5.0: The Next Development Release
  MySQL and the Future (the TODO)
    New Features Planned for 5.0
    New Features Planned for 5.1
    New Features Planned for the Near Future
    New Features Planned for the Mid-Term Future
    New Features We Don't Plan to Implement
  MySQL Information Sources
    MySQL Mailing Lists
      The MySQL Mailing Lists
      Asking Questions or Reporting Bugs
      How to Report Bugs or Problems
      Guidelines for Answering Questions on the Mailing List
    MySQL Community Support on IRC (Internet Relay Chat)
  MySQL Standards Compliance
    What Standards MySQL Follows
    Selecting SQL Modes
    Running MySQL in ANSI Mode
    MySQL Extensions to Standard SQL
    MySQL Differences from Standard SQL
      Subqueries
      `SELECT INTO TABLE'
      Transactions and Atomic Operations
      Stored Procedures and Triggers
      Foreign Keys
      Views
      `--' as the Start of a Comment
    How MySQL Deals with Constraints
      `PRIMARY KEY' and `UNIQUE' Index Constraints
      Constraints on Invalid Data
      `ENUM' and `SET' Constraints
    Known Errors and Design Deficiencies in MySQL
      Errors in 3.23 Fixed in a Later MySQL Version
      Errors in 4.0 Fixed in a Later MySQL Version
      Open Bugs and Design Deficiencies in MySQL

Installing MySQL
  General Installation Issues
    Operating Systems Supported by MySQL
    Choosing Which MySQL Distribution to Install
      Choosing Which Version of MySQL to Install
      Choosing a Distribution Format
      How and When Updates Are Released
      Release Philosophy--No Known Bugs in Releases
      MySQL Binaries Compiled by MySQL AB
    How to Get MySQL
    Verifying Package Integrity Using MD5 Checksums or `GnuPG'
      Verifying the MD5 Checksum
      Signature Checking Using `GnuPG'
      Signature Checking Using `RPM'
    Installation Layouts
  Standard MySQL Installation Using a Binary Distribution
    Installing MySQL on Windows
      Windows System Requirements
      Installing a Windows Binary Distribution
      Preparing the Windows MySQL Environment
      Selecting a Windows Server
      Starting the Server for the First Time
      Starting MySQL from the Windows Command Line
      Starting MySQL as a Windows Service
      Troubleshooting a MySQL Installation Under Windows
      Running MySQL Client Programs on Windows
      MySQL on Windows Compared to MySQL on Unix
    Installing MySQL on Linux
    Installing MySQL on Mac OS X
    Installing MySQL on NetWare
    Installing MySQL on Other Unix-Like Systems
  MySQL Installation Using a Source Distribution
    Source Installation Overview
    Typical `configure' Options
    Installing from the Development Source Tree
    Dealing with Problems Compiling MySQL
    MIT-pthreads Notes
    Installing MySQL from Source on Windows
      Building MySQL Using VC++
      Creating a Windows Source Package from the Latest Development Source
    Compiling MySQL Clients on Windows
  Post-Installation Setup and Testing
    Windows Post-Installation Procedures
    Unix Post-Installation Procedures
      Problems Running `mysql_install_db'
      Starting and Stopping MySQL Automatically
      Starting and Troubleshooting the MySQL Server
    Securing the Initial MySQL Accounts
  Upgrading/Downgrading MySQL
    Upgrading from Version 4.1 to 5.0
    Upgrading from Version 4.0 to 4.1
    Upgrading from Version 3.23 to 4.0
    Upgrading from Version 3.22 to 3.23
    Upgrading from Version 3.21 to 3.22
    Upgrading from Version 3.20 to 3.21
    Upgrading MySQL Under Windows
    Upgrading the Grant Tables
    Copying MySQL Databases to Another Machine
  Operating System-Specific Notes
    Linux Notes
      Linux Operating System Notes
      Linux Binary Distribution Notes
      Linux Source Distribution Notes
      Linux Post-Installation Notes
      Linux x86 Notes
      Linux SPARC Notes
      Linux Alpha Notes
      Linux PowerPC Notes
      Linux MIPS Notes
      Linux IA-64 Notes
    Mac OS X Notes
      Mac OS X 10.x (Darwin)
      Mac OS X Server 1.2 (Rhapsody)
    Solaris Notes
      Solaris 2.7/2.8 Notes
      Solaris x86 Notes
    BSD Notes
      FreeBSD Notes
      NetBSD Notes
      OpenBSD 2.5 Notes
      OpenBSD 2.8 Notes
      BSD/OS Version 2.x Notes
      BSD/OS Version 3.x Notes
      BSD/OS Version 4.x Notes
    Other Unix Notes
      HP-UX Version 10.20 Notes
      HP-UX Version 11.x Notes
      IBM-AIX notes
      SunOS 4 Notes
      Alpha-DEC-UNIX Notes (Tru64)
      Alpha-DEC-OSF/1 Notes
      SGI Irix Notes
      SCO Notes
      SCO UnixWare Version 7.1.x Notes
    OS/2 Notes
    BeOS Notes
  Perl Installation Notes
    Installing Perl on Unix
    Installing ActiveState Perl on Windows
    Problems Using the Perl `DBI'/`DBD' Interface

MySQL Tutorial
  Connecting to and Disconnecting from the Server
  Entering Queries
  Creating and Using a Database
    Creating and Selecting a Database
    Creating a Table
    Loading Data into a Table
    Retrieving Information from a Table
      Selecting All Data
      Selecting Particular Rows
      Selecting Particular Columns
      Sorting Rows
      Date Calculations
      Working with `NULL' Values
      Pattern Matching
      Counting Rows
      Using More Than one Table
  Getting Information About Databases and Tables
  Using `mysql' in Batch Mode
  Examples of Common Queries
    The Maximum Value for a Column
    The Row Holding the Maximum of a Certain Column
    Maximum of Column per Group
    The Rows Holding the Group-wise Maximum of a Certain Field
    Using User Variables
    Using Foreign Keys
    Searching on Two Keys
    Calculating Visits Per Day
    Using `AUTO_INCREMENT'
  Queries from the Twin Project
    Find All Non-distributed Twins
    Show a Table of Twin Pair Status
  Using MySQL with Apache

Using MySQL Programs
  Overview of MySQL Programs
  Invoking MySQL Programs
  Specifying Program Options
    Using Options on the Command Line
    Using Option Files
    Using Environment Variables to Specify Options
    Using Options to Set Program Variables

Database Administration
  The MySQL Server and Server Startup Scripts
    Overview of the Server-Side Scripts and Utilities
    The `mysqld-max' Extended MySQL Server
    The `mysqld_safe' Server Startup Script
    The `mysql.server' Server Startup Script
    The `mysqld_multi' Program for Managing Multiple MySQL Servers
  Configuring the MySQL Server
    `mysqld' Command-Line Options
    The Server SQL Mode
    Server System Variables
      Dynamic System Variables
    Server Status Variables
  The MySQL Server Shutdown Process
  General Security Issues
    General Security Guidelines
    Making MySQL Secure Against Attackers
    Startup Options for `mysqld' Concerning Security
    Security Issues with `LOAD DATA LOCAL'
  The MySQL Access Privilege System
    What the Privilege System Does
    How the Privilege System Works
    Privileges Provided by MySQL
    Connecting to the MySQL Server
    Access Control, Stage 1: Connection Verification
    Access Control, Stage 2: Request Verification
    When Privilege Changes Take Effect
    Causes of `Access denied' Errors
    Password Hashing in MySQL 4.1
      Implications of Password Hashing Changes for Application Programs
      Password Hashing in MySQL 4.1.0
  MySQL User Account Management
    MySQL Usernames and Passwords
    Adding New User Accounts to MySQL
    Removing User Accounts from MySQL
    Limiting Account Resources
    Assigning Account Passwords
    Keeping Your Password Secure
    Using Secure Connections
      Basic SSL Concepts
      Requirements
      Setting Up SSL Certificates for MySQL
      SSL `GRANT' Options
      SSL Command-Line Options
      Connecting to MySQL Remotely from Windows with SSH
  Disaster Prevention and Recovery
    Database Backups
    Table Maintenance and Crash Recovery
      `myisamchk' Invocation Syntax
      General Options for `myisamchk'
      Check Options for `myisamchk'
      Repair Options for `myisamchk'
      Other Options for `myisamchk'
      `myisamchk' Memory Usage
      Using `myisamchk' for Crash Recovery
      How to Check `MyISAM' Tables for Errors
      How to Repair Tables
      Table Optimization
    Setting Up a Table Maintenance Schedule
    Getting Information About a Table
  MySQL Localization and International Usage
    The Character Set Used for Data and Sorting
      Using the German Character Set
    Setting the Error Message Language
    Adding a New Character Set
    The Character Definition Arrays
    String Collating Support
    Multi-Byte Character Support
    Problems With Character Sets
    MySQL Server Time Zone Support
  The MySQL Log Files
    The Error Log
    The General Query Log
    The Update Log
    The Binary Log
    The Slow Query Log
    Log File Maintenance
  Running Multiple MySQL Servers on the Same Machine
    Running Multiple Servers on Windows
      Starting Multiple Windows Servers at the Command Line
      Starting Multiple Windows Servers as Services
    Running Multiple Servers on Unix
    Using Client Programs in a Multiple-Server Environment
  The MySQL Query Cache
    How the Query Cache Operates
    Query Cache `SELECT' Options
    Query Cache Configuration
    Query Cache Status and Maintenance

Replication in MySQL
  Introduction to Replication
  Replication Implementation Overview
  Replication Implementation Details
    Replication Master Thread States
    Replication Slave I/O Thread States
    Replication Slave SQL Thread States
    Replication Relay and Status Files
  How to Set Up Replication
  Replication Compatibility Between MySQL Versions
  Upgrading a Replication Setup
    Upgrading Replication to 4.0 or 4.1
    Upgrading Replication to 5.0
  Replication Features and Known Problems
  Replication Startup Options
  Replication FAQ
  Troubleshooting Replication
  Reporting Replication Bugs

MySQL Optimization
  Optimization Overview
    MySQL Design Limitations and Tradeoffs
    Designing Applications for Portability
    What We Have Used MySQL For
    The MySQL Benchmark Suite
    Using Your Own Benchmarks
  Optimizing `SELECT' Statements and Other Queries
    `EXPLAIN' Syntax (Get Information About a `SELECT')
    Estimating Query Performance
    Speed of `SELECT' Queries
    How MySQL Optimizes `WHERE' Clauses
    Range Optimization
      Range Access Method for Single-Part Indexes
      Range Access Method for Multiple-Part Indexes
    Index Merge Optimization
      Index Merge Intersection Access Algorithm
      Index Merge Union Access Algorithm
      Index Merge Sort-Union Access Algorithm
    How MySQL Optimizes `IS NULL'
    How MySQL Optimizes `DISTINCT'
    How MySQL Optimizes `LEFT JOIN' and `RIGHT JOIN'
    How MySQL Optimizes `ORDER BY'
    How MySQL Optimizes `GROUP BY'
      Loose index scan
      Tight index scan
    How MySQL Optimizes `LIMIT'
    How to Avoid Table Scans
    Speed of `INSERT' Statements
    Speed of `UPDATE' Statements
    Speed of `DELETE' Statements
    Other Optimization Tips
  Locking Issues
    Locking Methods
    Table Locking Issues
  Optimizing Database Structure
    Design Choices
    Make Your Data as Small as Possible
    Column Indexes
    Multiple-Column Indexes
    How MySQL Uses Indexes
    The `MyISAM' Key Cache
      Shared Key Cache Access
      Multiple Key Caches
      Midpoint Insertion Strategy
      Index Preloading
      Key Cache Block Size
      Restructuring a Key Cache
    How MySQL Counts Open Tables
    How MySQL Opens and Closes Tables
    Drawbacks to Creating Many Tables in the Same Database
  Optimizing the MySQL Server
    System Factors and Startup Parameter Tuning
    Tuning Server Parameters
    Controlling Query Optimizer Performance
    How Compiling and Linking Affects the Speed of MySQL
    How MySQL Uses Memory
    How MySQL Uses DNS
  Disk Issues
    Using Symbolic Links
      Using Symbolic Links for Databases on Unix
      Using Symbolic Links for Tables on Unix
      Using Symbolic Links for Databases on Windows

MySQL Client and Utility Programs
  Overview of the Client-Side Scripts and Utilities
  `myisampack', the MySQL Compressed Read-only Table Generator
  `mysql', the Command-Line Tool
    `mysql' Commands
    Executing SQL Statements from a Text File
    `mysql' Tips
      Displaying Query Results Vertically
      Using the `--safe-updates' Option
      Disabling `mysql' Auto-Reconnect
  `mysqladmin', Administering a MySQL Server
  The `mysqlbinlog' Binary Log Utility
  `mysqlcc', the MySQL Control Center
  The `mysqlcheck' Table Maintenance and Repair Program
  The `mysqldump' Database Backup Program
  The `mysqlhotcopy' Database Backup Program
  The `mysqlimport' Data Import Program
  `mysqlshow', Showing Databases, Tables, and Columns
  `perror', Explaining Error Codes
  The `replace' String-Replacement Utility

MySQL Language Reference

Language Structure
  Literal Values
    Strings
    Numbers
    Hexadecimal Values
    Boolean Values
    `NULL' Values
  Database, Table, Index, Column, and Alias Names
    Identifier Qualifiers
    Identifier Case Sensitivity
  User Variables
  System Variables
    Structured System Variables
  Comment Syntax
  Treatment of Reserved Words in MySQL

Character Set Support
  Character Sets and Collations in General
  Character Sets and Collations in MySQL
  Determining the Default Character Set and Collation
    Server Character Set and Collation
    Database Character Set and Collation
    Table Character Set and Collation
    Column Character Set and Collation
    Examples of Character Set and Collation Assignment
    Connection Character Sets and Collations
    Character String Literal Character Set and Collation
    Using `COLLATE' in SQL Statements
    `COLLATE' Clause Precedence
    `BINARY' Operator
    Some Special Cases Where the Collation Determination Is Tricky
    Collations Must Be for the Right Character Set
    An Example of the Effect of Collation
  Operations Affected by Character Set Support
    Result Strings
    `CONVERT()'
    `CAST()'
    `SHOW' Statements
  Unicode Support
  UTF8 for Metadata
  Compatibility with Other DBMSs
  New Character Set Configuration File Format
  National Character Set
  Upgrading Character Sets from MySQL 4.0
    4.0 Character Sets and Corresponding 4.1 Character Set/Collation Pairs
    Converting 4.0 Character Columns to 4.1 Format
  Character Sets and Collations That MySQL Supports
    Unicode Character Sets
    West European Character Sets
    Central European Character Sets
    South European and Middle East Character Sets
    Baltic Character Sets
    Cyrillic Character Sets
    Asian Character Sets

Column Types
  Column Type Overview
    Overview of Numeric Types
    Overview of Date and Time Types
    Overview of String Types
  Numeric Types
  Date and Time Types
    The `DATETIME', `DATE', and `TIMESTAMP' Types
      `TIMESTAMP' Properties Prior to MySQL 4.1
      `TIMESTAMP' Properties as of MySQL 4.1
    The `TIME' Type
    The `YEAR' Type
    Y2K Issues and Date Types
  String Types
    The `CHAR' and `VARCHAR' Types
    The `BLOB' and `TEXT' Types
    The `ENUM' Type
    The `SET' Type
  Column Type Storage Requirements
  Choosing the Right Type for a Column
  Using Column Types from Other Database Engines

Functions and Operators
  Operators
    Operator Precedence
    Parentheses
    Comparison Functions and Operators
    Logical Operators
  Control Flow Functions
  String Functions
    String Comparison Functions
  Numeric Functions
    Arithmetic Operators
    Mathematical Functions
  Date and Time Functions
  Full-Text Search Functions
    Boolean Full-Text Searches
    Full-Text Searches with Query Expansion
    Full-Text Restrictions
    Fine-Tuning MySQL Full-Text Search
    Full-Text Search TODO
  Cast Functions and Operators
  Other Functions
    Bit Functions
    Encryption Functions
    Information Functions
    Miscellaneous Functions
  Functions and Modifiers for Use with `GROUP BY' Clauses
    `GROUP BY' (Aggregate) Functions
    `GROUP BY' Modifiers
    `GROUP BY' with Hidden Fields

SQL Statement Syntax
  Data Manipulation Statements
    `DELETE' Syntax
    `DO' Syntax
    `HANDLER' Syntax
    `INSERT' Syntax
      `INSERT ... SELECT' Syntax
      `INSERT DELAYED' Syntax
    `LOAD DATA INFILE' Syntax
    `REPLACE' Syntax
    `SELECT' Syntax
      `JOIN' Syntax
      `UNION' Syntax
    Subquery Syntax
      The Subquery as Scalar Operand
      Comparisons Using Subqueries
      Subqueries with `ANY', `IN', and `SOME'
      Subqueries with `ALL'
      Correlated Subqueries
      `EXISTS' and `NOT EXISTS'
      Row Subqueries
      Subqueries in the `FROM' clause
      Subquery Errors
      Optimizing Subqueries
      Rewriting Subqueries as Joins for Earlier MySQL Versions
    `TRUNCATE' Syntax
    `UPDATE' Syntax
  Data Definition Statements
    `ALTER DATABASE' Syntax
    `ALTER TABLE' Syntax
    `ALTER VIEW' Syntax
    `CREATE DATABASE' Syntax
    `CREATE INDEX' Syntax
    `CREATE TABLE' Syntax
      Silent Column Specification Changes
    `CREATE VIEW' Syntax
    `DROP DATABASE' Syntax
    `DROP INDEX' Syntax
    `DROP TABLE' Syntax
    `DROP VIEW' Syntax
    `RENAME TABLE' Syntax
  MySQL Utility Statements
    `DESCRIBE' Syntax (Get Information About Columns)
    `USE' Syntax
  MySQL Transactional and Locking Statements
    `START TRANSACTION', `COMMIT', and `ROLLBACK' Syntax
    Statements That Cannot Be Rolled Back
    Statements That Cause an Implicit Commit
    `SAVEPOINT' and `ROLLBACK TO SAVEPOINT' Syntax
    `LOCK TABLES' and `UNLOCK TABLES' Syntax
    `SET TRANSACTION' Syntax
  Database Administration Statements
    Account Management Statements
      `DROP USER' Syntax
      `GRANT' and `REVOKE' Syntax
      `SET PASSWORD' Syntax
    Table Maintenance Statements
      `ANALYZE TABLE' Syntax
      `BACKUP TABLE' Syntax
      `CHECK TABLE' Syntax
      `CHECKSUM TABLE' Syntax
      `OPTIMIZE TABLE' Syntax
      `REPAIR TABLE' Syntax
      `RESTORE TABLE' Syntax
    `SET' and `SHOW' Syntax
      `SET' Syntax
      `SHOW CHARACTER SET' Syntax
      `SHOW COLLATION' Syntax
      `SHOW COLUMNS' Syntax
      `SHOW CREATE DATABASE' Syntax
      `SHOW CREATE TABLE' Syntax
      `SHOW CREATE VIEW' Syntax
      `SHOW DATABASES' Syntax
      `SHOW ENGINES' Syntax
      `SHOW ERRORS' Syntax
      `SHOW GRANTS' Syntax
      `SHOW INDEX' Syntax
      `SHOW INNODB STATUS' Syntax
      `SHOW LOGS' Syntax
      `SHOW PRIVILEGES' Syntax
      `SHOW PROCESSLIST' Syntax
      `SHOW STATUS' Syntax
      `SHOW TABLE STATUS' Syntax
      `SHOW TABLES' Syntax
      `SHOW VARIABLES' Syntax
      `SHOW WARNINGS' Syntax
    Other Administrative Statements
      `CACHE INDEX' Syntax
      `FLUSH' Syntax
      `KILL' Syntax
      `LOAD INDEX INTO CACHE' Syntax
      `RESET' Syntax
  Replication Statements
    SQL Statements for Controlling Master Servers
      `PURGE MASTER LOGS' Syntax
      `RESET MASTER' Syntax
      `SET SQL_LOG_BIN' Syntax
      `SHOW BINLOG EVENTS' Syntax
      `SHOW MASTER LOGS' Syntax
      `SHOW MASTER STATUS' Syntax
      `SHOW SLAVE HOSTS' Syntax
    SQL Statements for Controlling Slave Servers
      `CHANGE MASTER TO' Syntax
      `LOAD DATA FROM MASTER' Syntax
      `LOAD TABLE TBL_NAME FROM MASTER' Syntax
      `MASTER_POS_WAIT()' Syntax
      `RESET SLAVE' Syntax
      `SET GLOBAL SQL_SLAVE_SKIP_COUNTER' Syntax
      `SHOW SLAVE STATUS' Syntax
      `START SLAVE' Syntax
      `STOP SLAVE' Syntax
  SQL Syntax for Prepared Statements

MySQL Storage Engines and Table Types
  The `MyISAM' Storage Engine
    `MyISAM' Startup Options
    Space Needed for Keys
    `MyISAM' Table Storage Formats
      Static (Fixed-Length) Table Characteristics
      Dynamic Table Characteristics
      Compressed Table Characteristics
    `MyISAM' Table Problems
      Corrupted `MyISAM' Tables
      Problems from Tables Not Being Closed Properly
  The `MERGE' Storage Engine
    `MERGE' Table Problems
  The `MEMORY' (`HEAP') Storage Engine
  The `BDB' (`BerkeleyDB') Storage Engine
    Operating Systems Supported by `BDB'
    Installing `BDB'
    `BDB' Startup Options
    Characteristics of `BDB' Tables
    Things We Need to Fix for `BDB'
    Restrictions on `BDB' Tables
    Errors That May Occur When Using `BDB' Tables
  The `ISAM' Storage Engine

The `InnoDB' Storage Engine
  `InnoDB' Overview
  `InnoDB' Contact Information
  `InnoDB' in MySQL 3.23
  `InnoDB' Configuration
  `InnoDB' Startup Options
  Creating the `InnoDB' Tablespace
    Dealing with `InnoDB' Initialization Problems
  Creating `InnoDB' Tables
    How to Use Transactions in `InnoDB' with Different APIs
    Converting `MyISAM' Tables to `InnoDB'
    How an `AUTO_INCREMENT' Column Works in `InnoDB'
    `FOREIGN KEY' Constraints
    `InnoDB' and MySQL Replication
    Using Per-Table Tablespaces
  Adding and Removing `InnoDB' Data and Log Files
  Backing Up and Recovering an `InnoDB' Database
    Forcing Recovery
    Checkpoints
  Moving an `InnoDB' Database to Another Machine
  `InnoDB' Transaction Model and Locking
    `InnoDB' and `AUTOCOMMIT'
    `InnoDB' and `TRANSACTION ISOLATION LEVEL'
    Consistent Non-Locking Read
    Locking Reads `SELECT ... FOR UPDATE' and `SELECT ... LOCK IN SHARE MODE'
    Next-Key Locking: Avoiding the Phantom Problem
    An Example of How the Consistent Read Works in `InnoDB'
    Locks Set by Different SQL Statements in `InnoDB'
    When Does MySQL Implicitly Commit or Roll Back a Transaction?
    Deadlock Detection and Rollback
    How to Cope with Deadlocks
  `InnoDB' Performance Tuning Tips
    `SHOW INNODB STATUS' and the `InnoDB' Monitors
  Implementation of Multi-Versioning
  Table and Index Structures
    Physical Structure of an Index
    Insert Buffering
    Adaptive Hash Indexes
    Physical Record Structure
  File Space Management and Disk I/O
    Disk I/O
    Using Raw Devices for the Tablespace
    File Space Management
    Defragmenting a Table
  Error Handling
    `InnoDB' Error Codes
    Operating System Error Codes
  Restrictions on `InnoDB' Tables
  `InnoDB' Troubleshooting
    Troubleshooting `InnoDB' Data Dictionary Operations

MySQL Cluster
  MySQL Cluster Overview
  Basic MySQL Cluster Concepts
  MySQL Cluster Configuration
    Building from Source Code
    Installing the Software
    Quick Test Setup of MySQL Cluster
    Configuration File
      An Example Configuration in a MySQL Cluster
      Defining the Computers in a MySQL Cluster
      Defining the Management Server in a MySQL Cluster
      Defining the Storage Nodes in a MySQL Cluster
      Defining the MySQL Servers in a MySQL Cluster
      Defining TCP/IP Connections in a MySQL Cluster
      Defining Shared-Memory Connections in a MySQL Cluster
      Defining SCI Transporter Connections in a MySQL Cluster
  Process Management in MySQL Cluster
    MySQL Server Process Usage for MySQL Cluster
    `ndbd', the Storage Engine Node Process
    `ndb_mgmd', the Management Server Process
    `ndb_mgm', the Management Client Process
    Command Options for MySQL Cluster Processes
      MySQL Cluster-Related Command Options for `mysqld'
      Command Options for `ndbd'
      Command Options for `ndb_mgmd'
      Command Options for `ndb_mgm'
  Management of MySQL Cluster
    Commands in the Management Client
    Event Reports Generated in MySQL Cluster
      Logging Management Commands
      Log Events
    Single User Mode
    On-line Backup of MySQL Cluster
      Cluster Backup Concepts
      Using The Management Server to Create a Backup
      How to Restore a Cluster Backup
      Configuration for Cluster Backup
      Backup Troubleshooting
  Using High-Speed Interconnects with MySQL Cluster
    Configuring MySQL Cluster to use SCI Sockets
    Low-level benchmarks to understand impact of cluster interconnects

Introduction to MaxDB
  History of MaxDB
  Licensing and Support
  MaxDB-Related Links
  Basic Concepts of MaxDB
  Feature Differences Between MaxDB and MySQL
  Interoperability Features Between MaxDB and MySQL
  Reserved Words in MaxDB

Spatial Extensions in MySQL
  Introduction
  The OpenGIS Geometry Model
    The Geometry Class Hierarchy
    Class `Geometry'
    Class `Point'
    Class `Curve'
    Class `LineString'
    Class `Surface'
    Class `Polygon'
    Class `GeometryCollection'
    Class `MultiPoint'
    Class `MultiCurve'
    Class `MultiLineString'
    Class `MultiSurface'
    Class `MultiPolygon'
  Supported Spatial Data Formats
    Well-Known Text (WKT) Format
    Well-Known Binary (WKB) Format
  Creating a Spatially Enabled MySQL Database
    MySQL Spatial Data Types
    Creating Spatial Values
      Creating Geometry Values Using WKT Functions
      Creating Geometry Values Using WKB Functions
      Creating Geometry Values Using MySQL-Specific Functions
    Creating Spatial Columns
    Populating Spatial Columns
    Fetching Spatial Data
      Fetching Spatial Data in Internal Format
      Fetching Spatial Data in WKT Format
      Fetching Spatial Data in WKB Format
  Analyzing Spatial Information
    Geometry Format Conversion Functions
    `Geometry' Functions
      General Geometry Functions
      `Point' Functions
      `LineString' Functions
      `MultiLineString' Functions
      `Polygon' Functions
      `MultiPolygon' Functions
      `GeometryCollection' Functions
    Functions That Create New Geometries from Existing Ones
      Geometry Functions That Produce New Geometries
      Spatial Operators
    Functions for Testing Spatial Relations Between Geometric Objects
    Relations on Geometry Minimal Bounding Rectangles (MBRs)
    Functions That Test Spatial Relationships Between Geometries
  Optimizing Spatial Analysis
    Creating Spatial Indexes
    Using a Spatial Index
  MySQL Conformance and Compatibility
    GIS Features That Are Not Yet Implemented

Stored Procedures and Functions
  Stored Procedure Syntax
    Maintaining Stored Procedures
      `CREATE PROCEDURE' and `CREATE FUNCTION'
      `ALTER PROCEDURE' and `ALTER FUNCTION'
      `DROP PROCEDURE' and `DROP FUNCTION'
      `SHOW CREATE PROCEDURE' and `SHOW CREATE FUNCTION'
    `SHOW PROCEDURE STATUS' and `SHOW FUNCTION STATUS'
    `CALL' Statement
    `BEGIN ... END' Compound Statement
    `DECLARE' Statement
    Variables in Stored Procedures
      `DECLARE' Local Variables
      Variable `SET' Statement
      `SELECT ... INTO' Statement
    Conditions and Handlers
      `DECLARE' Conditions
      `DECLARE' Handlers
    Cursors
      Declaring Cursors
      Cursor `OPEN' Statement
      Cursor `FETCH' Statement
      Cursor `CLOSE' Statement
    Flow Control Constructs
      `IF' Statement
      `CASE' Statement
      `LOOP' Statement
      `LEAVE' Statement
      `ITERATE' Statement
      `REPEAT' Statement
      `WHILE' Statement

MySQL APIs
  MySQL Program Development Utilities
    `msql2mysql', Convert mSQL Programs for Use with MySQL
    `mysql_config', Get compile options for compiling clients
  MySQL C API
    C API Data types
    C API Function Overview
    C API Function Descriptions
      `mysql_affected_rows()'
      `mysql_change_user()'
      `mysql_character_set_name()'
      `mysql_close()'
      `mysql_connect()'
      `mysql_create_db()'
      `mysql_data_seek()'
      `mysql_debug()'
      `mysql_drop_db()'
      `mysql_dump_debug_info()'
      `mysql_eof()'
      `mysql_errno()'
      `mysql_error()'
      `mysql_escape_string()'
      `mysql_fetch_field()'
      `mysql_fetch_fields()'
      `mysql_fetch_field_direct()'
      `mysql_fetch_lengths()'
      `mysql_fetch_row()'
      `mysql_field_count()'
      `mysql_field_seek()'
      `mysql_field_tell()'
      `mysql_free_result()'
      `mysql_get_client_info()'
      `mysql_get_client_version()'
      `mysql_get_host_info()'
      `mysql_get_proto_info()'
      `mysql_get_server_info()'
      `mysql_get_server_version()'
      `mysql_info()'
      `mysql_init()'
      `mysql_insert_id()'
      `mysql_kill()'
      `mysql_list_dbs()'
      `mysql_list_fields()'
      `mysql_list_processes()'
      `mysql_list_tables()'
      `mysql_num_fields()'
      `mysql_num_rows()'
      `mysql_options()'
      `mysql_ping()'
      `mysql_query()'
      `mysql_real_connect()'
      `mysql_real_escape_string()'
      `mysql_real_query()'
      `mysql_reload()'
      `mysql_row_seek()'
      `mysql_row_tell()'
      `mysql_select_db()'
      `mysql_set_server_option()'
      `mysql_shutdown()'
      `mysql_sqlstate()'
      `mysql_ssl_set()'
      `mysql_stat()'
      `mysql_store_result()'
      `mysql_thread_id()'
      `mysql_use_result()'
      `mysql_warning_count()'
      `mysql_commit()'
      `mysql_rollback()'
      `mysql_autocommit()'
      `mysql_more_results()'
      `mysql_next_result()'
    C API Prepared Statements
    C API Prepared Statement Data types
    C API Prepared Statement Function Overview
    C API Prepared Statement Function Descriptions
      `mysql_stmt_affected_rows()'
      `mysql_stmt_attr_get()'
      `mysql_stmt_attr_set()'
      `mysql_stmt_bind_param()'
      `mysql_stmt_bind_result()'
      `mysql_stmt_close()'
      `mysql_stmt_data_seek()'
      `mysql_stmt_errno()'
      `mysql_stmt_error()'
      `mysql_stmt_execute()'
      `mysql_stmt_free_result()'
      `mysql_stmt_insert_id()'
      `mysql_stmt_fetch()'
      `mysql_stmt_fetch_column()'
      `mysql_stmt_field_count()'
      `mysql_stmt_init()'
      `mysql_stmt_num_rows()'
      `mysql_stmt_param_count()'
      `mysql_stmt_param_metadata()'
      `mysql_stmt_prepare()'
      `mysql_stmt_reset()'
      `mysql_stmt_result_metadata()'
      `mysql_stmt_row_seek()'
      `mysql_stmt_row_tell()'
      `mysql_stmt_send_long_data()'
      `mysql_stmt_sqlstate()'
      `mysql_stmt_store_result()'
    C API Prepared statement problems
    C API Handling of Multiple Query Execution
    C API Handling of Date and Time Values
    C API Threaded Function Descriptions
      `my_init()'
      `mysql_thread_init()'
      `mysql_thread_end()'
      `mysql_thread_safe()'
    C API Embedded Server Function Descriptions
      `mysql_server_init()'
      `mysql_server_end()'
    Common questions and problems when using the C API
      Why `mysql_store_result()' Sometimes Returns `NULL' After `mysql_query()' Returns Success
      What Results You Can Get from a Query
      How to Get the Unique ID for the Last Inserted Row
      Problems Linking with the C API
    Building Client Programs
    How to Make a Threaded Client
    libmysqld, the Embedded MySQL Server Library
      Overview of the Embedded MySQL Server Library
      Compiling Programs with `libmysqld'
      Restrictions when using the Embedded MySQL Server
      Using Option Files with the Embedded Server
      Things left to do in Embedded Server (TODO)
      A Simple Embedded Server Example
      Licensing the Embedded Server
  MySQL PHP API
    Common Problems with MySQL and PHP
  MySQL Perl API
  MySQL C++ API
    Borland C++
  MySQL Python API
  MySQL Tcl API
  MySQL Eiffel Wrapper

MySQL Connectors
  MySQL ODBC Support
    Introduction to MyODBC
      What is ODBC?
      What is Connector/ODBC?
      What is MyODBC 2.50?
      What is MyODBC 3.51?
      Where to Get MyODBC
      Supported Platforms
      MyODBC Mailing List
      How to Get MyODBC Support
      How to Report MyODBC Problems or Bugs
      How to Request a MyODBC Feature or Patch
      How to Submit a MyODBC Patch
    General Information About ODBC and MyODBC
      Introduction to ODBC
      MyODBC Architecture
      ODBC Driver Managers
      Types of MySQL ODBC Drivers
    How to Install MyODBC
    Installing MyODBC from a Binary Distribution on Windows
    Installing MyODBC from a Binary Distribution on Unix
      Installing MyODBC from an RPM Distribution
      Installing MyODBC from a Binary Tarball Distribution
    Installing MyODBC from a Source Distribution on Windows
      Requirements
      Building MyODBC 3.51
      Testing
      Building MyODBC 2.50
    Installing MyODBC from a Source Distribution on Unix
      Requirements
      Typical `configure' Options
      Thread-Safe Client
      Shared or Static Options
      Enabling Debugging Information
      Enabling the Documentation
      Building and Compilation
      Building Shared Libraries
      Installing Driver Libraries
      Testing MyODBC on Unix
      Mac OS X Notes
      HP-UX Notes
      AIX Notes:
    Installing MyODBC from the BitKeeper Development Source Tree
    MyODBC Configuration
      What is a Data Source Name?
      Configuring a MyODBC DSN on Windows
      Configuring a MyODBC DSN on Unix
      Connection Parameters
      Connecting Without a Predefined DSN
      Establishing a Remote Connection to System A from System B
      Getting an ODBC Trace File
      Applications Tested with MyODBC
      Programs Known to Work With MyODBC
    MyODBC Connection-Related Issues
      While Configuring a MyODBC DSN, a `Could Not Load Translator or Setup Library' Error Occurs
      While Connecting, an `Access denied' Error Occurs
      INFO: About ODBC Connection Pooling
    MyODBC and Microsoft Access
      How to Set Up Microsoft Access to Work with MySQL using MyODBC?
      How to Export a Table or Query from Access to MySQL?
      How to Import or Link MySQL Database Tables to Access?
      The Structure or Location of a Linked Table has been Changed. Can I See Those Changes Locally in Linked Tables?
      When I Insert or Update a Record in Linked Tables, I Get `#DELETED#'
      How Do I Handle Write Conflicts or Row Location Errors?
      Whenever I Export a Table from Access 97, a Strange Syntax Error Occurs
      Access Returns `Another user has modified the record that you have modified' While Editing Records
      How to Trap ODBC Login Error Messages in Access?
      How Do I Optimize Access for Performance with MyODBC?
      I Have Very Long Tables. What is the Best Configuration for MyODBC to Access These Tables?
      How to Set the QueryTimeout Value for ODBC Connections?
      INFO: Tools to Export/Import from/to Access to/from MySQL
    MyODBC and Microsoft VBA and ASP
      Why Does `SELECT COUNT(*) FROM TBL_NAME' Return an Error?
      Whenever I Use the `AppendChunk()' or `GetChunk()' ADO Methods, I Get an Error `Multiple-step operation generated errors. Check each status value'.
      How to Find the Total Number of Rows Affected by a Particular SQL Statement in ADO?
      How Do I Handle Blob Data in Visual Basic?
      How Do I Map Visual Basic Data Types to MySQL Types?
      SAMPLES: VB with ADO, DAO and RDO
      ASP and MySQL with MyODBC
      INFO: Frequently Asked Questions on ActiveX Data Objects (ADO)
    MyODBC and Third-Party ODBC Tools
      How to Retrieve Data from MySQL into MS-Word/Excel Documents?
      Exporting Tables from MS DTS to MySQL Using MyODBC Results in a Syntax Error
      HOWTO: Configure MySQL+MyODBC+unixODBC+ColdFusion on Solaris
    MyODBC General Functionality
      How to Get the Value of an `AUTO_INCREMENT' Column in ODBC
      Does MyODBC Support Dynamic Cursor Type?
      What Causes `Transactions are not enabled' Errors?
      What Causes `Cursor not found' Errors?
      Can I Use MyODBC 2.50 Applications with MyODBC 3.51?
      Can I Access MySQL from .NET Environment Using MyODBC?
      Why Does MyODBC Perform Poorly, and Also Make a Lot of Disk Activity for Relatively Small Queries?
    Basic MyODBC Application Steps
    MyODBC API Reference
    MyODBC Data Types
    MyODBC Error Codes
    MyODBC With VB: ADO, DAO and RDO
      ADO: `rs.addNew', `rs.delete', and `rs.update'
      DAO: `rs.addNew', `rs.update', and Scrolling
      RDO: `rs.addNew' and `rs.update'
    MyODBC with Microsoft .NET
      ODBC.NET: CSHARP(C#)
      ODBC.NET: VB
    Credits
  MySQL Java Connectivity (JDBC)

Error Handling in MySQL

Extending MySQL
  MySQL Internals
    MySQL Threads
    MySQL Test Suite
      Running the MySQL Test Suite
      Extending the MySQL Test Suite
      Reporting Bugs in the MySQL Test Suite
  Adding New Functions to MySQL
    `CREATE FUNCTION/DROP FUNCTION' Syntax
    Adding a New User-defined Function
      UDF Calling Sequences for simple functions
      UDF Calling Sequences for aggregate functions
      Argument Processing
      Return Values and Error Handling
      Compiling and Installing User-defined Functions
    Adding a New Native Function
  Adding New Procedures to MySQL
    Procedure Analyse
    Writing a Procedure

Problems and Common Errors
  How to Determine What Is Causing a Problem
  Common Errors When Using MySQL Programs
    `Access denied'
    `Can't connect to [local] MySQL server'
    `Client does not support authentication protocol'
    Password Fails When Entered Interactively
    `Host 'HOST_NAME' is blocked'
    `Too many connections'
    `Out of memory'
    `MySQL server has gone away'
    `Packet too large'
    Communication Errors and Aborted Connections
    `The table is full'
    `Can't create/write to file'
    `Commands out of sync'
    `Ignoring user'
    `Table 'TBL_NAME' doesn't exist'
    `Can't initialize character set'
    File Not Found
  Installation-Related Issues
    Problems Linking to the MySQL Client Library
    How to Run MySQL as a Normal User
    Problems with File Permissions
  Administration-Related Issues
    How to Reset the Root Password
    What to Do If MySQL Keeps Crashing
    How MySQL Handles a Full Disk
    Where MySQL Stores Temporary Files
    How to Protect or Change the MySQL Socket File `/tmp/mysql.sock'
    Time Zone Problems
  Query-Related Issues
    Case Sensitivity in Searches
    Problems Using `DATE' Columns
    Problems with `NULL' Values
    Problems with Column Aliases
    Rollback Failure for Non-Transactional Tables
    Deleting Rows from Related Tables
    Solving Problems with No Matching Rows
    Problems with Floating-Point Comparisons
  Optimizer-Related Issues
  Table Definition-Related Issues
    Problems with `ALTER TABLE'
    How to Change the Order of Columns in a Table
    `TEMPORARY TABLE' Problems

Credits
  Developers at MySQL AB
  Contributors to MySQL
  Documenters and translators
  Libraries used by and included with MySQL
  Packages that support MySQL
  Tools that were used to create MySQL
  Supporters of MySQL

MySQL Change History
  Changes in release 5.0.x (Development)
    Changes in release 5.0.2 (not released yet)
    Changes in release 5.0.1 (27 Jul 2004)
    Changes in release 5.0.0 (22 Dec 2003: Alpha)
  Changes in release 4.1.x (Gamma)
    Changes in release 4.1.8 (not released yet)
    Changes in release 4.1.7 (23 Oct 2004: Production)
    Changes in release 4.1.6 (10 Oct 2004)
    Changes in release 4.1.5 (16 Sep 2004)
    Changes in release 4.1.4 (26 Aug 2004: Gamma)
    Changes in release 4.1.3 (28 Jun 2004: Beta)
    Changes in release 4.1.2 (28 May 2004)
    Changes in release 4.1.1 (01 Dec 2003)
    Changes in release 4.1.0 (03 Apr 2003: Alpha)
  Changes in release 4.0.x (Production)
    Changes in release 4.0.23 (not released yet)
    Changes in release 4.0.22 (to be released soon)
    Changes in release 4.0.21 (06 Sep 2004)
    Changes in release 4.0.20 (17 May 2004)
    Changes in release 4.0.19 (04 May 2004)
    Changes in release 4.0.18 (12 Feb 2004)
    Changes in release 4.0.17 (14 Dec 2003)
    Changes in release 4.0.16 (17 Oct 2003)
    Changes in release 4.0.15 (03 Sep 2003)
    Changes in release 4.0.14 (18 Jul 2003)
    Changes in release 4.0.13 (16 May 2003)
    Changes in release 4.0.12 (15 Mar 2003: Production)
    Changes in release 4.0.11 (20 Feb 2003)
    Changes in release 4.0.10 (29 Jan 2003)
    Changes in release 4.0.9 (09 Jan 2003)
    Changes in release 4.0.8 (07 Jan 2003)
    Changes in release 4.0.7 (20 Dec 2002)
    Changes in release 4.0.6 (14 Dec 2002: Gamma)
    Changes in release 4.0.5 (13 Nov 2002)
    Changes in release 4.0.4 (29 Sep 2002)
    Changes in release 4.0.3 (26 Aug 2002: Beta)
    Changes in release 4.0.2 (01 Jul 2002)
    Changes in release 4.0.1 (23 Dec 2001)
    Changes in release 4.0.0 (Oct 2001: Alpha)
  Changes in release 3.23.x (Recent; still supported)
    Changes in release 3.23.59 (not released yet)
    Changes in release 3.23.58 (11 Sep 2003)
    Changes in release 3.23.57 (06 Jun 2003)
    Changes in release 3.23.56 (13 Mar 2003)
    Changes in release 3.23.55 (23 Jan 2003)
    Changes in release 3.23.54 (05 Dec 2002)
    Changes in release 3.23.53 (09 Oct 2002)
    Changes in release 3.23.52 (14 Aug 2002)
    Changes in release 3.23.51 (31 May 2002)
    Changes in release 3.23.50 (21 Apr 2002)
    Changes in release 3.23.49 (14 Feb 2002)
    Changes in release 3.23.48 (07 Feb 2002)
    Changes in release 3.23.47 (27 Dec 2001)
    Changes in release 3.23.46 (29 Nov 2001)
    Changes in release 3.23.45 (22 Nov 2001)
    Changes in release 3.23.44 (31 Oct 2001)
    Changes in release 3.23.43 (04 Oct 2001)
    Changes in release 3.23.42 (08 Sep 2001)
    Changes in release 3.23.41 (11 Aug 2001)
    Changes in release 3.23.40 (18 Jul 2001)
    Changes in release 3.23.39 (12 Jun 2001)
    Changes in release 3.23.38 (09 May 2001)
    Changes in release 3.23.37 (17 Apr 2001)
    Changes in release 3.23.36 (27 Mar 2001)
    Changes in release 3.23.35 (15 Mar 2001)
    Changes in release 3.23.34a (11 Mar 2001)
    Changes in release 3.23.34 (10 Mar 2001)
    Changes in release 3.23.33 (09 Feb 2001)
    Changes in release 3.23.32 (22 Jan 2001)
    Changes in release 3.23.31 (17 Jan 2001: Production)
    Changes in release 3.23.30 (04 Jan 2001)
    Changes in release 3.23.29 (16 Dec 2000)
    Changes in release 3.23.28 (22 Nov 2000: Gamma)
    Changes in release 3.23.27 (24 Oct 2000)
    Changes in release 3.23.26 (18 Oct 2000)
    Changes in release 3.23.25 (29 Sep 2000)
    Changes in release 3.23.24 (08 Sep 2000)
    Changes in release 3.23.23 (01 Sep 2000)
    Changes in release 3.23.22 (31 Jul 2000)
    Changes in release 3.23.21 (04 Jul 2000)
    Changes in release 3.23.20 (28 Jun 2000: Beta)
    Changes in release 3.23.19
    Changes in release 3.23.18 (11 Jun 2000)
    Changes in release 3.23.17 (07 Jun 2000)
    Changes in release 3.23.16 (16 May 2000)
    Changes in release 3.23.15 (08 May 2000)
    Changes in release 3.23.14 (09 Apr 2000)
    Changes in release 3.23.13 (14 Mar 2000)
    Changes in release 3.23.12 (07 Mar 2000)
    Changes in release 3.23.11 (16 Feb 2000)
    Changes in release 3.23.10 (30 Jan 2000)
    Changes in release 3.23.9 (29 Jan 2000)
    Changes in release 3.23.8 (02 Jan 2000)
    Changes in release 3.23.7 (10 Dec 1999)
    Changes in release 3.23.6 (15 Nov 1999)
    Changes in release 3.23.5 (20 Oct 1999)
    Changes in release 3.23.4 (28 Sep 1999)
    Changes in release 3.23.3 (13 Sep 1999)
    Changes in release 3.23.2 (09 Aug 1999)
    Changes in release 3.23.1 (08 Jul 1999)
    Changes in release 3.23.0 (05 Jul 1999: Alpha)
  Changes in release 3.22.x (Old; discontinued)
    Changes in release 3.22.35
    Changes in release 3.22.34
    Changes in release 3.22.33
    Changes in release 3.22.32 (14 Feb 2000)
    Changes in release 3.22.31
    Changes in release 3.22.30 (11 Jan 2000)
    Changes in release 3.22.29 (02 Jan 2000)
    Changes in release 3.22.28 (20 Oct 1999)
    Changes in release 3.22.27 (05 Oct 1999)
    Changes in release 3.22.26 (16 Sep 1999)
    Changes in release 3.22.25 (07 Jun 1999)
    Changes in release 3.22.24 (05 Jul 1999)
    Changes in release 3.22.23 (08 Jun 1999)
    Changes in release 3.22.22 (30 Apr 1999)
    Changes in release 3.22.21 (04 Apr 1999)
    Changes in release 3.22.20 (18 Mar 1999)
    Changes in release 3.22.19 (01 Mar 1999)
    Changes in release 3.22.18 (26 Feb 1999)
    Changes in release 3.22.17 (22 Feb 1999: Production)
    Changes in release 3.22.16 (05 Feb 1999)
    Changes in release 3.22.15 (27 Jan 1999)
    Changes in release 3.22.14 (01 Jan 1999: Gamma)
    Changes in release 3.22.13 (16 Dec 1998)
    Changes in release 3.22.12 (09 Dec 1998)
    Changes in release 3.22.11 (24 Nov 1998)
    Changes in release 3.22.10 (04 Nov 1998)
    Changes in release 3.22.9 (19 Oct 1998)
    Changes in release 3.22.8 (06 Oct 1998)
    Changes in release 3.22.7 (21 Sep 1998: Beta)
    Changes in release 3.22.6 (31 Aug 1998)
    Changes in release 3.22.5 (20 Aug 1998: Alpha)
    Changes in release 3.22.4 (06 Jul 1998: Beta)
    Changes in release 3.22.3 (30 Jun 1998)
    Changes in release 3.22.2
    Changes in release 3.22.1 (Jun 1998)
    Changes in release 3.22.0 (18 May 1998: Alpha)
  Changes in release 3.21.x
    Changes in release 3.21.33 (08 Jul 1998)
    Changes in release 3.21.32 (30 Jun 1998)
    Changes in release 3.21.31 (10 Jun 1998)
    Changes in release 3.21.30
    Changes in release 3.21.29
    Changes in release 3.21.28
    Changes in release 3.21.27
    Changes in release 3.21.26
    Changes in release 3.21.25
    Changes in release 3.21.24
    Changes in release 3.21.23
    Changes in release 3.21.22
    Changes in release 3.21.21a
    Changes in release 3.21.21
    Changes in release 3.21.20
    Changes in release 3.21.19
    Changes in release 3.21.18
    Changes in release 3.21.17
    Changes in release 3.21.16
    Changes in release 3.21.15
    Changes in release 3.21.14b
    Changes in release 3.21.14a
    Changes in release 3.21.13
    Changes in release 3.21.12
    Changes in release 3.21.11
    Changes in release 3.21.10
    Changes in release 3.21.9
    Changes in release 3.21.8
    Changes in release 3.21.7
    Changes in release 3.21.6
    Changes in release 3.21.5
    Changes in release 3.21.4
    Changes in release 3.21.3
    Changes in release 3.21.2
    Changes in release 3.21.0
  Changes in release 3.20.x
    Changes in release 3.20.18
    Changes in release 3.20.17
    Changes in release 3.20.16
    Changes in release 3.20.15
    Changes in release 3.20.14
    Changes in release 3.20.13
    Changes in release 3.20.11
    Changes in release 3.20.10
    Changes in release 3.20.9
    Changes in release 3.20.8
    Changes in release 3.20.7
    Changes in release 3.20.6
    Changes in release 3.20.3
    Changes in release 3.20.0
  Changes in release 3.19.x
    Changes in release 3.19.5
    Changes in release 3.19.4
    Changes in release 3.19.3
  `InnoDB' Change History
    MySQL/InnoDB-4.0.21, September 10, 2004
    MySQL/InnoDB-4.1.4, August 31, 2004
    MySQL/InnoDB-4.1.3, June 28, 2004
    MySQL/InnoDB-4.1.2, May 30, 2004
    MySQL/InnoDB-4.0.20, May 18, 2004
    MySQL/InnoDB-4.0.19, May 4, 2004
    MySQL/InnoDB-4.0.18, February 13, 2004
    MySQL/InnoDB-5.0.0, December 24, 2003
    MySQL/InnoDB-4.0.17, December 17, 2003
    MySQL/InnoDB-4.1.1, December 4, 2003
    MySQL/InnoDB-4.0.16, October 22, 2003
    MySQL/InnoDB-3.23.58, September 15, 2003
    MySQL/InnoDB-4.0.15, September 10, 2003
    MySQL/InnoDB-4.0.14, July 22, 2003
    MySQL/InnoDB-3.23.57, June 20, 2003
    MySQL/InnoDB-4.0.13, May 20, 2003
    MySQL/InnoDB-4.1.0, April 3, 2003
    MySQL/InnoDB-3.23.56, March 17, 2003
    MySQL/InnoDB-4.0.12, March 18, 2003
    MySQL/InnoDB-4.0.11, February 25, 2003
    MySQL/InnoDB-4.0.10, February 4, 2003
    MySQL/InnoDB-3.23.55, January 24, 2003
    MySQL/InnoDB-4.0.9, January 14, 2003
    MySQL/InnoDB-4.0.8, January 7, 2003
    MySQL/InnoDB-4.0.7, December 26, 2002
    MySQL/InnoDB-4.0.6, December 19, 2002
    MySQL/InnoDB-3.23.54, December 12, 2002
    MySQL/InnoDB-4.0.5, November 18, 2002
    MySQL/InnoDB-3.23.53, October 9, 2002
    MySQL/InnoDB-4.0.4, October 2, 2002
    MySQL/InnoDB-4.0.3, August 28, 2002
    MySQL/InnoDB-3.23.52, August 16, 2002
    MySQL/InnoDB-4.0.2, July 10, 2002
    MySQL/InnoDB-3.23.51, June 12, 2002
    MySQL/InnoDB-3.23.50, April 23, 2002
    MySQL/InnoDB-3.23.49, February 17, 2002
    MySQL/InnoDB-3.23.48, February 9, 2002
    MySQL/InnoDB-3.23.47, December 28, 2001
    MySQL/InnoDB-4.0.1, December 23, 2001
    MySQL/InnoDB-3.23.46, November 30, 2001
    MySQL/InnoDB-3.23.45, November 23, 2001
    MySQL/InnoDB-3.23.44, November 2, 2001
    MySQL/InnoDB-3.23.43, October 4, 2001
    MySQL/InnoDB-3.23.42, September 9, 2001
    MySQL/InnoDB-3.23.41, August 13, 2001
    MySQL/InnoDB-3.23.40, July 16, 2001
    MySQL/InnoDB-3.23.39, June 13, 2001
    MySQL/InnoDB-3.23.38, May 12, 2001
  `MySQL Cluster' Change History
    MySQL Cluster-4.1.7, (not released yet)
    MySQL Cluster-4.1.6, 10 Oct 2004
    MySQL Cluster-4.1.5, 16 Sep 2004
    MySQL Cluster-4.1.4, 31 Aug 2004
    MySQL Cluster-5.0.1, 27 Jul 2004
    MySQL Cluster-4.1.3, 28 Jun 2004

Porting to Other Systems
  Debugging a MySQL Server
    Compiling MySQL for Debugging
    Creating Trace Files
    Debugging `mysqld' under `gdb'
    Using a Stack Trace
    Using Log Files to Find Cause of Errors in `mysqld'
    Making a Test Case If You Experience Table Corruption
  Debugging a MySQL Client
  The DBUG Package
  Comments about RTS Threads
  Differences Between Thread Packages

Environment Variables

MySQL Regular Expressions

GNU General Public License

MySQL FLOSS License Exception

SQL Command, Type, and Function Index

Concept Index


This is the Reference Manual for the MySQL Database System.  It
documents MySQL up to Version 4.0.22, but is also applicable for older
versions of the MySQL software (such as 3.23 or 4.0-production) because
functional changes are indicated with reference to a version number.

General Information
*******************

The MySQL (R) software delivers a very fast, multi-threaded,
multi-user, and robust SQL (Structured Query Language) database server.
MySQL Server is intended for mission-critical, heavy-load production
systems as well as for embedding into mass-deployed software.  MySQL is
a registered trademark of MySQL AB.

The MySQL software is Dual Licensed. Users can choose to use the MySQL
software as an Open Source/Free Software product under the terms of the
GNU General Public License (`http://www.fsf.org/licenses/') or can
purchase a standard commercial license from MySQL AB.  *Note Licensing
and Support::.

The MySQL Web site (`http://www.mysql.com/') provides the latest
information about the MySQL software.

The following list describes some sections of particular interest in
this manual:

   * For information about the company behind the MySQL Database Server,
     see *Note What is MySQL AB::.

   * For a discussion about the capabilities of the MySQL Database
     Server, see *Note Features::.

   * For installation instructions, see *Note Installing::.

   * For tips on porting the MySQL Database Software to new
     architectures or operating systems, see *Note Porting::.

   * For information about upgrading from a Version 4.0 release, see
     *Note Upgrading-from-4.0::.

   * For information about upgrading from a Version 3.23 release, see
     *Note Upgrading-from-3.23::.

   * For information about upgrading from a Version 3.22 release, see
     *Note Upgrading-from-3.22::.

   * For a tutorial introduction to the MySQL Database Server, see
     *Note Tutorial::.

   * For examples of SQL and benchmarking information, see the
     benchmarking directory (`sql-bench' in the distribution).

   * For a history of new features and bugfixes, see *Note News::.

   * For a list of currently known bugs and misfeatures, see *Note
     Bugs::.

   * For future plans, see *Note TODO::.

   * For a list of all the contributors to this project, see *Note
     Credits::.

*Important*:

Reports of errors (often called "bugs"), as well as questions and
comments, should be sent to the general MySQL mailing list.  *Note
Mailing-list::.  *Note Bug reports::.

The `mysqlbug' script should be used to generate bug reports on Unix.
(Windows distributions contain a file named `mysqlbug.txt' in the base
directory that can be used as a template for a bug report.)

For source distributions, the `mysqlbug' script can be found in the
`scripts' directory. For binary distributions, `mysqlbug' can be found
in the `bin' directory (`/usr/bin' for the `MySQL-server' RPM package).

If you have found a sensitive security bug in MySQL Server, please let
us know immediately by sending an email message to <[e-mail]>.

About This Manual
=================

This is the Reference Manual for the MySQL Database System.  It
documents MySQL up to Version 4.0.22, but is also applicable for older
versions of the MySQL software (such as 3.23 or 4.0-production) because
functional changes are indicated with reference to a version number.

Because this manual serves as a reference, it does not provide general
instruction on SQL or relational database concepts. It also will not
teach you how to use your operating system or command-line interpreter.

The MySQL Database Software is under constant development, and the
Reference Manual is updated frequently as well.  The most recent
version of the manual is available online in searchable form at
`http://dev.mysql.com/doc/'.  Other formats also are available,
including HTML, PDF, and Windows CHM versions.

The primary document is the Texinfo file.  The HTML version is produced
automatically using a modified version of `texi2html'.  The plain text
and Info versions are produced with `makeinfo'.  The PostScript version
is produced using `texi2dvi' and `dvips'.  The PDF version is produced
with `pdftex'.

If you have any suggestions concerning additions or corrections to this
manual, please send them to the documentation team at <[e-mail]>.

This manual was initially written by David Axmark and Michael "Monty"
Widenius. It is now maintained by the MySQL Documentation Team,
consisting of Arjen Lentz, Paul DuBois, and Stefan Hinz.  For the many
other contributors, see *Note Credits::.

The copyright (2004) to this manual is owned by the Swedish company
MySQL AB. *Note Copyright::.  MySQL and the MySQL logo are (registered)
trademarks of MySQL AB.  Other trademarks and registered trademarks
referred to in this manual are the property of their respective owners,
and are used for identification purposes only.

Conventions Used in This Manual
-------------------------------

This manual uses certain typographical conventions:

`constant'
     Constant-width font is used for command names and options; SQL
     statements; database, table, and column names; C and Perl code;
     and environment variables.  Example: "To see how `mysqladmin'
     works, invoke it with the `--help' option."

CONSTANT ITALIC
     Italic constant-width font is used to indicate variable input for
     which you should substitute a value of your own choosing.

`filename'
     Constant-width font with surrounding quotes is used for filenames
     and pathnames.  Example: "The distribution is installed under the
     `/usr/local/' directory."

`c'
     Constant-width font with surrounding quotes is also used to
     indicate character sequences.  Example: "To specify a wildcard,
     use the `%' character."

_italic_
     Italic font is used for emphasis, _like this_.

*boldface*
     Boldface font is used in table headings and to convey *especially
     strong emphasis*.

When commands are shown that are meant to be executed from within a
particular program, the program is indicated by a prompt shown before
the command.  For example, `shell>' indicates a command that you
execute from your login shell, and `mysql>' indicates a statement that
you execute from the `mysql' client program:

     shell> type a shell command here
     mysql> type a mysql statement here

The "shell" is your command interpreter. On Unix, this is typically a
program such as `sh' or `csh'. On Windows, the equivalent program is
`command.com' or `cmd.exe', typically run in a console window.

When you enter a command or statement shown in an example, do not type
the prompt shown in the example.

Database, table, and column names must often be substituted into
statements.  To indicate that such substitution is necessary, this
manual uses DB_NAME, TBL_NAME, and COL_NAME.  For example, you might
see a statement like this:

     mysql> SELECT COL_NAME FROM DB_NAME.TBL_NAME;

This means that if you were to enter a similar statement, you would
supply your own database, table, and column names, perhaps like this:

     mysql> SELECT author_name FROM biblio_db.author_list;

SQL keywords are not case sensitive and may be written in uppercase or
lowercase.  This manual uses uppercase.

In syntax descriptions, square brackets (`[' and `]') are used to
indicate optional words or clauses.  For example, in the following
statement, `IF EXISTS' is optional:

     DROP TABLE [IF EXISTS] TBL_NAME

When a syntax element consists of a number of alternatives, the
alternatives are separated by vertical bars (`|').  When one member
from a set of choices _may_ be chosen, the alternatives are listed
within square brackets (`[' and `]'):

     TRIM([[BOTH | LEADING | TRAILING] [REMSTR] FROM] STR)

When one member from a set of choices _must_ be chosen, the
alternatives are listed within braces (`{' and `}'):

     {DESCRIBE | DESC} TBL_NAME [COL_NAME | WILD]

An ellipsis (`...') indicates the omission of a section of a statement,
typically to provide a shorter version of more complex syntax. For
example, `INSERT ... SELECT' is shorthand for the form of `INSERT'
statement that is followed by a `SELECT' statement.

An ellipsis can also indicate that the preceding syntax element of a
statement may be repeated. In the following example, multiple
RESET_OPTION values may be given, with each of those after the first
preceded by commas:

     RESET RESET_OPTION [,RESET_OPTION] ...

Commands for setting shell variables are shown using Bourne shell
syntax.  For example, the sequence to set an environment variable and
run a command looks like this in Bourne shell syntax:

     shell> VARNAME=VALUE SOME_COMMAND

If you are using `csh' or `tcsh', you must issue commands somewhat
differently.  You would execute the sequence just shown like this:

     shell> setenv VARNAME VALUE
     shell> SOME_COMMAND

Overview of the MySQL Database Management System
================================================

MySQL, the most popular Open Source SQL database management system, is
developed, distributed, and supported by MySQL AB.  MySQL AB is a
commercial company, founded by the MySQL developers.  It is a second
generation open source company that unites open source values and
methodology with a successful business model.  *Note What is MySQL AB::.

The MySQL Web site (`http://www.mysql.com/') provides the latest
information about MySQL software and MySQL AB.

MySQL is a database management system.
     A database is a structured collection of data.  It may be anything
     from a simple shopping list to a picture gallery or the vast
     amounts of information in a corporate network.  To add, access,
     and process data stored in a computer database, you need a
     database management system such as MySQL Server.  Since computers
     are very good at handling large amounts of data, database
     management systems play a central role in computing, as standalone
     utilities or as parts of other applications.

MySQL is a relational database management system.
     A relational database stores data in separate tables rather than
     putting all the data in one big storeroom.  This adds speed and
     flexibility.  The SQL part of "MySQL" stands for "Structured Query
     Language." SQL is the most common standardized language used to
     access databases and is defined by the ANSI/ISO SQL Standard. The
     SQL standard has been evolving since 1986 and several versions
     exist. In this manual, "SQL-92" refers to the standard released in
     1992, "SQL:1999" refers to the standard released in 1999, and
     "SQL:2003" refers to the current version of the standard.  We use
     the phrase "the SQL standard" to mean the current version of the
     SQL Standard at any time.

MySQL software is Open Source.
     Open Source means that it is possible for anyone to use and modify
     the software.  Anybody can download the MySQL software from the
     Internet and use it without paying anything.  If you wish, you may
     study the source code and change it to suit your needs.  The MySQL
     software uses the GPL (GNU General Public License),
     `http://www.fsf.org/licenses/', to define what you may and may not
     do with the software in different situations.  If you feel
     uncomfortable with the GPL or need to embed MySQL code into a
     commercial application, you can buy a commercially licensed
     version from us.  *Note MySQL licenses::.

The MySQL Database Server is very fast, reliable, and easy to use.
     If that is what you are looking for, you should give it a try.
     MySQL Server also has a practical set of features developed in
     close cooperation with our users.  You can find a performance
     comparison of MySQL Server with other database managers on our
     benchmark page.  *Note MySQL Benchmarks::.

     MySQL Server was originally developed to handle large databases
     much faster than existing solutions and has been successfully used
     in highly demanding production environments for several years.
     Although under constant development, MySQL Server today offers a
     rich and useful set of functions.  Its connectivity, speed, and
     security make MySQL Server highly suited for accessing databases
     on the Internet.

MySQL Server works in client/server or embedded systems.
     The MySQL Database Software is a client/server system that consists
     of a multi-threaded SQL server that supports different backends,
     several different client programs and libraries, administrative
     tools, and a wide range of application programming interfaces
     (APIs).

     We also provide MySQL Server as an embedded multi-threaded library
     that you can link into your application to get a smaller, faster,
     easier-to-manage product.

A large amount of contributed MySQL software is available.
     It is very likely that you will find that your favorite
     application or language already supports the MySQL Database Server.

The official way to pronounce "MySQL" is "My Ess Que Ell" (not "my
sequel"), but we don't mind if you pronounce it as "my sequel" or in
some other localized way.

History of MySQL
----------------

We started out with the intention of using `mSQL' to connect to our
tables using our own fast low-level (ISAM) routines. However, after some
testing, we came to the conclusion that `mSQL' was not fast enough or
flexible enough for our needs.  This resulted in a new SQL interface to
our database but with almost the same API interface as `mSQL'.  This
API was designed to allow third-party code that was written for use
with `mSQL' to be ported easily for use with MySQL.

The derivation of the name MySQL is not clear.  Our base directory and
a large number of our libraries and tools have had the prefix "my" for
well over 10 years.  However, co-founder Monty Widenius's daughter is
also named My.  Which of the two gave its name to MySQL is still a
mystery, even for us.

The name of the MySQL Dolphin (our logo) is "Sakila," which was chosen
by the founders of MySQL AB from a huge list of names suggested by users
in our "Name the Dolphin" contest. The winning name was submitted by
Ambrose Twebaze, an Open Source software developer from Swaziland,
Africa.  According to Ambrose, the name Sakila has its roots in
SiSwati, the local language of Swaziland. Sakila is also the name of a
town in Arusha, Tanzania, near Ambrose's country of origin, Uganda.

The Main Features of MySQL
--------------------------

The following list describes some of the important characteristics of
the MySQL Database Software. See also *Note Roadmap:: for more
information about current and upcoming features.

Internals and Portability
        * Written in C and C++.

        * Tested with a broad range of different compilers.

        * Works on many different platforms.  *Note Which OS::.

        * Uses GNU Automake, Autoconf, and Libtool for portability.

        * APIs for C, C++, Eiffel, Java, Perl, PHP, Python, Ruby, and
          Tcl are available.  *Note MySQL APIs::.

        * Fully multi-threaded using kernel threads.  It can easily use
          multiple CPUs if they are available.

        * Provides transactional and non-transactional storage engines.

        * Uses very fast B-tree disk tables (`MyISAM') with index
          compression.

        * Relatively easy to add another storage engine. This is useful
          if you want to add an SQL interface to an in-house database.

        * A very fast thread-based memory allocation system.

        * Very fast joins using an optimized one-sweep multi-join.

        * In-memory hash tables, which are used as temporary tables.

        * SQL functions are implemented using a highly optimized class
          library and should be as fast as possible.  Usually there is
          no memory allocation at all after query initialization.

        * The MySQL code is tested with Purify (a commercial memory
          leakage detector) as well as with Valgrind, a GPL tool
          (`http://developer.kde.org/~sewardj/').

        * The server is available as a separate program for use in a
          client/server networked environment.  It is also available as
          a library that can be embedded (linked) into standalone
          applications. Such applications can be used in isolation or
          in environments where no network is available.

Column Types
        * Many column types: signed/unsigned integers 1, 2, 3, 4, and 8
          bytes long, `FLOAT', `DOUBLE', `CHAR', `VARCHAR', `TEXT',
          `BLOB', `DATE', `TIME', `DATETIME', `TIMESTAMP', `YEAR',
          `SET', `ENUM', and OpenGIS spatial types.  *Note Column
          types::.

        * Fixed-length and variable-length records.

Statements and Functions
        * Full operator and function support in the `SELECT' and `WHERE'
          clauses of queries.  For example:

               mysql> SELECT CONCAT(first_name, ' ', last_name)
                   -> FROM citizen
                   -> WHERE income/dependents > 10000 AND age > 30;

        * Full support for SQL `GROUP BY' and `ORDER BY' clauses.
          Support for group functions (`COUNT()', `COUNT(DISTINCT ...)',
          `AVG()', `STD()', `SUM()', `MAX()', `MIN()', and
          `GROUP_CONCAT()').

        * Support for `LEFT OUTER JOIN' and `RIGHT OUTER JOIN' with
          both standard SQL and ODBC syntax.

        * Support for aliases on tables and columns as required by
          standard SQL.

        * `DELETE', `INSERT', `REPLACE', and `UPDATE' return the number
          of rows that were changed (affected).  It is possible to
          return the number of rows matched instead by setting a flag
          when connecting to the server.

        * The MySQL-specific `SHOW' command can be used to retrieve
          information about databases, tables, and indexes.  The
          `EXPLAIN' command can be used to determine how the optimizer
          resolves a query.

        * Function names do not clash with table or column names.  For
          example, `ABS' is a valid column name.  The only restriction
          is that for a function call, no spaces are allowed between
          the function name and the `(' that follows it.  *Note
          Reserved words::.

        * You can mix tables from different databases in the same query
          (as of MySQL 3.22).

Security
        * A privilege and password system that is very flexible and
          secure, and that allows host-based verification.  Passwords
          are secure because all password traffic is encrypted when you
          connect to a server.

Scalability and Limits
        * Handles large databases.  We use MySQL Server with databases
          that contain 50 million records. We also know of users who
          use MySQL Server with 60,000 tables and about 5,000,000,000
          rows.

        * Up to 64 indexes per table are allowed (32 before MySQL
          4.1.2).  Each index may consist of 1 to 16 columns or parts
          of columns.  The maximum index width is 1000 bytes (500
          before MySQL 4.1.2).  An index may use a prefix of a column
          for `CHAR', `VARCHAR', `BLOB', or `TEXT' column types.

Connectivity
        * Clients can connect to the MySQL server using TCP/IP sockets
          on any platform.  On Windows systems in the NT family (NT,
          2000, or XP), clients can connect using named pipes. On Unix
          systems, clients can connect using Unix domain socket files.

        * The Connector/ODBC (MyODBC) interface provides MySQL support
          for client programs that use ODBC (Open Database
          Connectivity) connections.  For example, you can use MS
          Access to connect to your MySQL server.  Clients can be run
          on Windows or Unix.  MyODBC source is available.  All ODBC
          2.5 functions are supported, as are many others.  *Note ODBC
          Connector::.

        * The Connector/J interface provides MySQL support for Java
          client programs that use JDBC connections.  Clients can be
          run on Windows or Unix.  Connector/J source is available.
          *Note Java Connector::.

Localization
        * The server can provide error messages to clients in many
          languages.  *Note Languages::.

        * Full support for several different character sets, including
          `latin1' (ISO-8859-1), `german', `big5', `ujis', and more.
          For example, the Scandinavian characters `a^', `a"' and `o"'
          are allowed in table and column names.  Unicode support is
          available as of MySQL 4.1.

        * All data is saved in the chosen character set.  All
          comparisons for normal string columns are case-insensitive.

        * Sorting is done according to the chosen character set (using
          Swedish collation by default).  It is possible to change this
          when the MySQL server is started.  To see an example of very
          advanced sorting, look at the Czech sorting code.  MySQL
          Server supports many different character sets that can be
          specified at compile time and runtime.

Clients and Tools
        * The MySQL server has built-in support for SQL statements to
          check, optimize, and repair tables.  These statements are
          available from the command line through the `mysqlcheck'
          client. MySQL also includes `myisamchk', a very fast
          command-line utility for performing these operations on
          `MyISAM' tables.  *Note MySQL Database Administration::.

        * All MySQL programs can be invoked with the `--help' or `-?'
          options to obtain online assistance.

MySQL Stability
---------------

This section addresses the questions, "_How stable is MySQL Server?_"
and, "_Can I depend on MySQL Server in this project?_" We will try to
clarify these issues and answer some important questions that concern
many potential users. The information in this section is based on data
gathered from the mailing lists, which are very active in identifying
problems as well as reporting types of use.

The original code stems back to the early 1980s. It provides a stable
code base, and the `ISAM' table format used by the original storage
engine remains backward-compatible.  At TcX, the predecessor of MySQL
AB, MySQL code has worked in projects since mid-1996, without any
problems.  When the MySQL Database Software initially was released to a
wider public, our new users quickly found some pieces of untested code.
Each new release since then has had fewer portability problems, even
though each new release has also had many new features.

Each release of the MySQL Server has been usable. Problems have occurred
only when users try code from the "gray zones."  Naturally, new users
don't know what the gray zones are; this section therefore attempts to
document those areas that are currently known.  The descriptions mostly
deal with Version 3.23, 4.0 and 4.1 of MySQL Server.  All known and
reported bugs are fixed in the latest version, with the exception of
those listed in the bugs section, which are design-related.  *Note
Bugs::.

The MySQL Server design is multi-layered with independent modules.
Some of the newer modules are listed here with an indication of how
well-tested each of them is:

Replication (Stable)
     Large groups of servers using replication are in production use,
     with good results. Work on enhanced replication features is
     continuing in MySQL 5.x.

`InnoDB' tables (Stable)
     The `InnoDB' transactional storage engine has been declared stable
     in the MySQL 3.23 tree, starting from version 3.23.49.  `InnoDB'
     is being used in large, heavy-load production systems.

`BDB' tables (Stable)
     The `Berkeley DB' code is very stable, but we are still improving
     the `BDB' transactional storage engine interface in MySQL Server.

Full-text searches (Stable)
     Full-text searching is widely used.  Important feature
     enhancements were added in MySQL 4.0 and 4.1.

`MyODBC' 3.51 (Stable)
     `MyODBC' 3.51 uses ODBC SDK 3.51 and is in wide production use.
     Some issues brought up appear to be application-related and
     independent of the ODBC driver or underlying database server.

How Big MySQL Tables Can Be
---------------------------

MySQL 3.22 had a 4GB (4 gigabyte) limit on table size. With the
`MyISAM' storage engine in MySQL 3.23, the maximum table size was
increased to 8 million terabytes (2 ^ 63 bytes). With this larger
allowed table size, the maximum effective table size for MySQL
databases now usually is determined by operating system constraints on
file sizes, not by MySQL internal limits.

The `InnoDB' storage engine maintains `InnoDB' tables within a
tablespace that can be created from several files. This allows a table
to exceed the maximum individual file size. The tablespace can include
raw disk partitions, which allows extremely large tables. The maximum
tablespace size is 64TB.

The following table lists some examples of operating system file-size
limits:

*Operating System*     *File-size Limit*
Linux-Intel 32-bit     2GB, much more when using LFS
Linux-Alpha            8TB (?)
Solaris 2.5.1          2GB (4GB possible with patch)
Solaris 2.6            4GB (can be changed with flag)
Solaris 2.7 Intel      4GB
Solaris 2.7            512GB
UltraSPARC
NetWare w/NSS          8TB
filesystem

On Linux 2.2, you can get `MyISAM' tables larger than 2GB in size by
using the Large File Support (LFS) patch for the ext2 filesystem. On
Linux 2.4, patches also exist for ReiserFS to get support for big
files. Most current Linux distributions are based on kernel 2.4 and
already include all the required LFS patches. However, the maximum
available file size still depends on several factors, one of them being
the filesystem used to store MySQL tables.

For a detailed overview about LFS in Linux, have a look at Andreas
Jaeger's `Large File Support in Linux' page at
`http://www.suse.de/~aj/linux_lfs.html'.

By default, MySQL creates `MyISAM' tables with an internal structure
that allows a maximum size of about 4GB.  You can check the maximum
table size for a table with the `SHOW TABLE STATUS' statement or with
`myisamchk -dv TBL_NAME'.  *Note `SHOW': SHOW.

If you need a `MyISAM' table that will be larger than 4GB in size (and
your operating system supports large files), the `CREATE TABLE'
statement allows `AVG_ROW_LENGTH' and `MAX_ROWS' options.  *Note
`CREATE TABLE': CREATE TABLE.  You can also change these options with
`ALTER TABLE' after the table has been created, to increase the table's
maximum allowable size.  *Note `ALTER TABLE': ALTER TABLE.

Other ways to work around file-size limits for `MyISAM' tables are as
follows:

   * If your large table is read-only, you can use `myisampack' to
     compress it.  `myisampack' usually compresses a table by at least
     50%, so you can have, in effect, much bigger tables.  `myisampack'
     also can merge multiple tables into a single table.  *Note
     `myisampack': myisampack.

   * Another way to get around the operating system file limit for
     `MyISAM' data files is by using the `RAID' options.  *Note `CREATE
     TABLE': CREATE TABLE.

   * MySQL includes a `MERGE' library that allows you to handle a
     collection of `MyISAM' tables that have identical structure as a
     single `MERGE' table.  *Note `MERGE' tables: MERGE.


Year 2000 Compliance
--------------------

The MySQL Server itself has no problems with Year 2000 (Y2K) compliance:

   * MySQL Server uses Unix time functions that handle dates into the
     year `2037' for `TIMESTAMP' values. For `DATE' and `DATETIME'
     values, dates through the year `9999' are accepted.

   * All MySQL date functions are implemented in one source file,
     `sql/time.cc', and are coded very carefully to be year 2000-safe.

   * In MySQL 3.22 and later, the `YEAR' column type can store years
     `0' and `1901' to `2155' in one byte and display them using two or
     four digits.  All two-digit years are considered to be in the range
     `1970' to `2069', which means that if you store `01' in a `YEAR'
     column, MySQL Server treats it as `2001'.

The following simple demonstration illustrates that MySQL Server has no
problems with `DATE' or `DATETIME' values through the year 9999, and no
problems with `TIMESTAMP' values until after the year 2030:

     mysql> DROP TABLE IF EXISTS y2k;
     Query OK, 0 rows affected (0.01 sec)

     mysql> CREATE TABLE y2k (date DATE,
         ->                   date_time DATETIME,
         ->                   time_stamp TIMESTAMP);
     Query OK, 0 rows affected (0.01 sec)

     mysql> INSERT INTO y2k VALUES
         -> ('1998-12-31','1998-12-31 23:59:59',19981231235959),
         -> ('1999-01-01','1999-01-01 00:00:00',19990101000000),
         -> ('1999-09-09','1999-09-09 23:59:59',19990909235959),
         -> ('2000-01-01','2000-01-01 00:00:00',20000101000000),
         -> ('2000-02-28','2000-02-28 00:00:00',20000228000000),
         -> ('2000-02-29','2000-02-29 00:00:00',20000229000000),
         -> ('2000-03-01','2000-03-01 00:00:00',20000301000000),
         -> ('2000-12-31','2000-12-31 23:59:59',20001231235959),
         -> ('2001-01-01','2001-01-01 00:00:00',20010101000000),
         -> ('2004-12-31','2004-12-31 23:59:59',20041231235959),
         -> ('2005-01-01','2005-01-01 00:00:00',20050101000000),
         -> ('2030-01-01','2030-01-01 00:00:00',20300101000000),
         -> ('2040-01-01','2040-01-01 00:00:00',20400101000000),
         -> ('9999-12-31','9999-12-31 23:59:59',99991231235959);
     Query OK, 14 rows affected (0.01 sec)
     Records: 14  Duplicates: 0  Warnings: 2

     mysql> SELECT * FROM y2k;
     +------------+---------------------+----------------+
     | date       | date_time           | time_stamp     |
     +------------+---------------------+----------------+
     | 1998-12-31 | 1998-12-31 23:59:59 | 19981231235959 |
     | 1999-01-01 | 1999-01-01 00:00:00 | 19990101000000 |
     | 1999-09-09 | 1999-09-09 23:59:59 | 19990909235959 |
     | 2000-01-01 | 2000-01-01 00:00:00 | 20000101000000 |
     | 2000-02-28 | 2000-02-28 00:00:00 | 20000228000000 |
     | 2000-02-29 | 2000-02-29 00:00:00 | 20000229000000 |
     | 2000-03-01 | 2000-03-01 00:00:00 | 20000301000000 |
     | 2000-12-31 | 2000-12-31 23:59:59 | 20001231235959 |
     | 2001-01-01 | 2001-01-01 00:00:00 | 20010101000000 |
     | 2004-12-31 | 2004-12-31 23:59:59 | 20041231235959 |
     | 2005-01-01 | 2005-01-01 00:00:00 | 20050101000000 |
     | 2030-01-01 | 2030-01-01 00:00:00 | 20300101000000 |
     | 2040-01-01 | 2040-01-01 00:00:00 | 00000000000000 |
     | 9999-12-31 | 9999-12-31 23:59:59 | 00000000000000 |
     +------------+---------------------+----------------+
     14 rows in set (0.00 sec)

The final two `TIMESTAMP' column values are zero because the year
values (`2040', `9999') exceed the `TIMESTAMP' maximum.  The
`TIMESTAMP' data type, which is used to store the current time,
supports values that range from `19700101000000' to `20300101000000' on
32-bit machines (signed value).  On 64-bit machines, `TIMESTAMP'
handles values up to `2106' (unsigned value).

Although MySQL Server itself is Y2K-safe, you may run into problems if
you use it with applications that are not Y2K-safe.  For example, many
old applications store or manipulate years using two-digit values
(which are ambiguous) rather than four-digit values.  This problem may
be compounded by applications that use values such as `00' or `99' as
"missing" value indicators.  Unfortunately, these problems may be
difficult to fix because different applications may be written by
different programmers, each of whom may use a different set of
conventions and date-handling functions.

Thus, even though MySQL Server has no Y2K problems, it is the
application's responsibility to provide unambiguous input.  See *Note
Y2K issues:: for MySQL Server's rules for dealing with ambiguous date
input data that contains two-digit year values.

Overview of MySQL AB
====================

MySQL AB is the company of the MySQL founders and main developers.
MySQL AB was originally established in Sweden by David Axmark, Allan
Larsson, and Michael "Monty" Widenius.

The developers of the MySQL server are all employed by the company.  We
are a virtual organization with people in a dozen countries around the
world. We communicate extensively over the Internet every day with one
another and with our users, supporters, and partners.

We are dedicated to developing the MySQL database software and
promoting it to new users. MySQL AB owns the copyright to the MySQL
source code, the MySQL logo and (registered) trademark, and this
manual. *Note What-is::.

The MySQL core values show our dedication to MySQL and Open Source.

These core values direct how MySQL AB works with the MySQL server
software:

   * To be the best and the most widely used database in the world

   * To be available and affordable by all

   * To be easy to use

   * To be continuously improved while remaining fast and safe

   * To be fun to use and improve

   * To be free from bugs

These are the core values of the company MySQL AB and its employees:

   * We subscribe to the Open Source philosophy and support the Open
     Source community

   * We aim to be good citizens

   * We prefer partners that share our values and mindset

   * We answer email and provide support

   * We are a virtual company, networking with others

   * We work against software patents

The MySQL Web site (`http://www.mysql.com/') provides the latest
information about MySQL and MySQL AB.

By the way, the "AB" part of the company name is the acronym for the
Swedish "aktiebolag," or "stock company." It translates to "MySQL,
Inc." In fact, MySQL, Inc. and MySQL GmbH are examples of MySQL AB
subsidiaries. They are located in the US and Germany, respectively.

The Business Model and Services of MySQL AB
-------------------------------------------

One of the most common questions we encounter is, "_How can you make a
living from something you give away for free?_" This is how:

   * MySQL AB makes money on support, services, commercial licenses,
     and royalties.

   * We use these revenues to fund product development and to expand
     the MySQL business.

The company has been profitable since its inception. In October 2001,
we accepted venture financing from leading Scandinavian investors and a
handful of business angels. This investment is used to solidify our
business model and build a basis for sustainable growth.

Support
.......

MySQL AB is run and owned by the founders and main developers of the
MySQL database. The developers are committed to providing support to
customers and other users in order to stay in touch with their needs
and problems. All our support is provided by qualified developers.
Really tricky questions are answered by Michael "Monty" Widenius,
principal author of the MySQL Server.

Paying customers receive high-quality support directly from MySQL AB.
MySQL AB also provides the MySQL mailing lists as a community resource
where anyone may ask questions.

For more information and ordering support at various levels, see *Note
Licensing and Support::.

Training and Certification
..........................

MySQL AB delivers MySQL and related training worldwide.  We offer both
open courses and in-house courses tailored to the specific needs of
your company. MySQL Training is also available through our partners,
the Authorized MySQL Training Centers.

Our training material uses the same sample databases used in our
documentation and our sample applications, and is always updated to
reflect the latest MySQL version. Our trainers are backed by the
development team to guarantee the quality of the training and the
continuous development of the course material. This also ensures that
no questions raised during the courses remain unanswered.

Attending our training courses will enable you to achieve your MySQL
application goals. You will also:
   * Save time

   * Improve the performance of your applications

   * Reduce or eliminate the need for additional hardware, decreasing
     cost

   * Enhance security.

   * Increase customer and co-worker satisfaction

   * Prepare yourself for MySQL Certification

If you are interested in our training as a potential participant or as
a training partner, please visit the training section at
`http://www.mysql.com/training/', or send email to <[e-mail]>.

For details about the MySQL Certification Program, please see
`http://www.mysql.com/certification/'.

Consulting
..........

MySQL AB and its Authorized Partners offer consulting services to users
of MySQL Server and to those who embed MySQL Server in their own
software, all over the world.

Our consultants can help you design and tune your databases, construct
efficient queries, tune your platform for optimal performance, resolve
migration issues, set up replication, build robust transactional
applications, and more.  We also help customers embed MySQL Server in
their products and applications for large-scale deployment.

Our consultants work in close collaboration with our development team,
which ensures the technical quality of our professional services.
Consulting assignments range from two-day power-start sessions to
projects that span weeks and months. Our expertise covers not only
MySQL Server, it also extends into programming and scripting languages
such as PHP, Perl, and more.

If you are interested in our consulting services or want to become a
consulting partner, please visit the consulting section of our Web site
at `http://www.mysql.com/consulting/' or contact our consulting staff
at <[e-mail]>.

Commercial Licenses
...................

The MySQL database is released under the GNU General Public License
(GPL).  This means that the MySQL software can be used free of charge
under the GPL. If you do not want to be bound by the GPL terms (such as
the requirement that your application must also be GPL), you may
purchase a commercial license for the same product from MySQL AB; see
`https://order.mysql.com/'.  Since MySQL AB owns the copyright to the
MySQL source code, we are able to employ Dual Licensing, which means
that the same product is available under GPL and under a commercial
license. This does not in any way affect the Open Source commitment of
MySQL AB. For details about when a commercial license is required,
please see *Note MySQL licenses::.

We also sell commercial licenses of third-party Open Source GPL
software that adds value to MySQL Server. A good example is the
`InnoDB' transactional storage engine that offers `ACID' support,
row-level locking, crash recovery, multi-versioning, foreign key
support, and more. *Note InnoDB::.

Partnering
..........

MySQL AB has a worldwide partner program that covers training courses,
consulting and support, publications, plus reselling and distributing
MySQL and related products. MySQL AB Partners get visibility on the
`http://www.mysql.com/' Web site and the right to use special versions
of the MySQL (registered) trademarks to identify their products and
promote their business.

If you are interested in becoming a MySQL AB Partner, please email
<[e-mail]>.

The word MySQL and the MySQL dolphin logo are (registered) trademarks
of MySQL AB. *Note MySQL AB Logos and Trademarks::.  These trademarks
represent a significant value that the MySQL founders have built over
the years.

The MySQL Web site (`http://www.mysql.com/') is popular among
developers and users. In December 2003, we served 16 million page views.
Our visitors represent a group that makes purchase decisions and
recommendations for both software and hardware. Twelve percent of our
visitors authorize purchase decisions, and only nine percent have no
involvement at all in purchase decisions. More than 65% have made one or
more online business purchases within the last half-year, and 70% plan
to make one in the next few months.

Contact Information
-------------------

The MySQL Web site (`http://www.mysql.com/') provides the latest
information about MySQL and MySQL AB.

For press services and inquiries not covered in our news releases
(`http://www.mysql.com/news-and-events/'), please send email to
<[e-mail]>.

If you have a support contract with MySQL AB, you will get timely,
precise answers to your technical questions about the MySQL software.
For more information, see *Note Support::.  On our Web site, see
`http://www.mysql.com/support/', or send email to <[e-mail]>.

For information about MySQL training, please visit the training section
at `http://www.mysql.com/training/', or send email to
<[e-mail]>.  *Note Business Services Training::.

For information on the MySQL Certification Program, please see
`http://www.mysql.com/certification/'.  *Note Business Services
Training::.

If you're interested in consulting, please visit the consulting section
of our Web site at `http://www.mysql.com/consulting/', or send email to
<[e-mail]>.  *Note Business Services Consulting::.

Commercial licenses may be purchased online at
`https://order.mysql.com/'. There you will also find information on how
to fax your purchase order to MySQL AB. More information about
licensing can be found at `http://www.mysql.com/products/licensing/'.
If you have questions regarding licensing or you want a quote for
high-volume licensing, please fill in the contact form on our Web site
(`http://www.mysql.com/'), or send email to <[e-mail]> (for
licensing questions) or to <[e-mail]> (for sales inquiries).
*Note MySQL licenses::.

If you represent a business that is interested in partnering with MySQL
AB, please send email to <[e-mail]>.  *Note Business Services
Partnering::.

For more information on the MySQL trademark policy, refer to
`http://www.mysql.com/company/trademark.html', or send email to
<[e-mail]>.  *Note MySQL AB Logos and Trademarks::.

If you are interested in any of the MySQL AB jobs listed in our jobs
section (`http://www.mysql.com/company/jobs/'), please send email to
<[e-mail]>.  Please do not send your CV as an attachment, but
rather as plain text at the end of your email message.

For general discussion among our many users, please direct your
attention to the appropriate mailing list.  *Note Questions::.

Reports of errors (often called "bugs"), as well as questions and
comments, should be sent to the general MySQL mailing list.  *Note
Mailing-list::.  If you have found a sensitive security bug in MySQL
Server, please let us know immediately by sending email to
<[e-mail]>.  *Note Bug reports::.

If you have benchmark results that we can publish, please contact us
via email at <[e-mail]>.

If you have suggestions concerning additions or corrections to this
manual, please send them to the documentation team via email at
<[e-mail]>.

For questions or comments about the workings or content of the MySQL
Web site (`http://www.mysql.com/'), please send email to
<[e-mail]>.

MySQL AB has a privacy policy, which can be read at
`http://www.mysql.com/company/privacy.html'.  For any queries regarding
this policy, please send email to <[e-mail]>.

For all other inquiries, please send email to <[e-mail]>.

MySQL Support and Licensing
===========================

This section describes MySQL support and licensing arrangements.

Support Offered by MySQL AB
---------------------------

Technical support from MySQL AB means individualized answers to your
unique problems direct from the software engineers who code the MySQL
database engine.

We try to take a broad and inclusive view of technical support. Almost
any problem involving MySQL software is important to us if it's
important to you.  Typically customers seek help on how to get
different commands and utilities to work, remove performance
bottlenecks, restore crashed systems, understand the impact of
operating system or networking issues on MySQL, set up best practices
for backup and recovery, utilize APIs, and so on.  Our support covers
only the MySQL server and our own utilities, not third-party products
that access the MySQL server, although we try to help with these where
we can.

Detailed information about our various support options is given at
`http://www.mysql.com/support/', where support contracts can also be
ordered online.  To contact our sales staff, send email to
<[e-mail]>.

Technical support is like life insurance. You can live happily without
it for years. However, when your hour arrives, it becomes critically
important, but it's too late to buy it.  If you use MySQL Server for
important applications and encounter sudden difficulties, it may be too
time-consuming to figure out all the answers yourself. You may need
immediate access to the most experienced MySQL troubleshooters
available, those employed by MySQL AB.

Copyrights and Licenses Used by MySQL
-------------------------------------

MySQL AB owns the copyright to the MySQL source code, the MySQL logos
and (registered) trademarks, and this manual.  *Note What is MySQL AB::.
Several different licenses are relevant to the MySQL distribution:

  1. All the MySQL-specific source in the server, the `mysqlclient'
     library and the client, as well as the GNU `readline' library, are
     covered by the GNU General Public License.  *Note GPL license::.
     The text of this license can be found as the file `COPYING' in
     MySQL distributions.

  2. The GNU `getopt' library is covered by the GNU Lesser General
     Public License.  See `http://www.fsf.org/licenses/'.

  3. Some parts of the source (the `regexp' library) are covered by a
     Berkeley-style copyright.

  4. Older versions of MySQL (3.22 and earlier) are subject to a
     stricter license
     (`http://www.mysql.com/products/licensing/mypl.html').  See the
     documentation of the specific version for information.

  5. The MySQL Reference Manual is _not_ distributed under a GPL-style
     license. Use of the manual is subject to the following terms:
        * Conversion to other formats is allowed, but the actual content
          may not be altered or edited in any way.

        * You may create a printed copy for your own personal use.

        * For all other uses, such as selling printed copies or using
          (parts of) the manual in another publication, prior written
          agreement from MySQL AB is required.
     Please send an email message to <[e-mail]> for more
     information or if you are interested in doing a translation.

For information about how the MySQL licenses work in practice, please
refer to *Note MySQL licenses:: and *Note MySQL AB Logos and
Trademarks::.

MySQL Licenses
--------------

The MySQL software is released under the GNU General Public License
(GPL), which is probably the best known Open Source license.  The
formal terms of the GPL license can be found at
`http://www.fsf.org/licenses/'.  See also
`http://www.fsf.org/licenses/gpl-faq.html' and
`http://www.gnu.org/philosophy/enforcing-gpl.html'.

Our GPL licensing is supported by an optional license exception that
enables many Free/Libre and Open Source Software ("FLOSS") applications
to include the GPL-licensed MySQL client libraries despite the fact
that not all FLOSS licenses are compatible with the GPL. For details,
see `http://www.mysql.com/products/licensing/foss-exception.html'.

Because the MySQL software is released under the GPL, it may often be
used for free, but for certain uses you may want or need to buy
commercial licenses from MySQL AB at `https://order.mysql.com/'.  See
`http://www.mysql.com/products/licensing/' for more information.

Older versions of MySQL (3.22 and earlier) are subject to a stricter
license (`http://www.mysql.com/products/licensing/mypl.html').  See the
documentation of the specific version for information.

Please note that the use of the MySQL software under commercial
license, GPL, or the old MySQL license does not automatically give you
the right to use MySQL AB (registered) trademarks.  *Note MySQL AB
Logos and Trademarks::.

Using the MySQL Software Under a Commercial License
...................................................

The GPL license is contagious in the sense that when a program is
linked to a GPL program, all the source code for all the parts of the
resulting product must also be released under the GPL.  If you do not
follow this GPL requirement, you break the license terms and forfeit
your right to use the GPL program altogether.  You also risk damages.

You need a commercial license under these conditions:

   * When you link a program with any GPL code from the MySQL software
     and don't want the resulting product to be licensed under GPL,
     perhaps because you want to build a commercial product or keep the
     added non-GPL code closed source for other reasons. When purchasing
     commercial licenses, you are not using the MySQL software under
     GPL even though it's the same code.

   * When you distribute a non-GPL application that works _only_ with
     the MySQL software and ship it with the MySQL software. This type
     of solution is considered to be linking even if it's done over a
     network.

   * When you distribute copies of the MySQL software without providing
     the source code as required under the GPL license.

   * When you want to support the further development of the MySQL
     database even if you don't formally need a commercial license.
     Purchasing support directly from MySQL AB is another good way of
     contributing to the development of the MySQL software, with
     immediate advantages for you.  *Note Support::.

Our GPL licensing is supported by an optional license exception that
enables many Free/Libre and Open Source Software ("FLOSS") applications
to include the GPL-licensed MySQL client libraries despite the fact
that not all FLOSS licenses are compatible with the GPL. For details,
see `http://www.mysql.com/products/licensing/foss-exception.html'.

If you require a commercial license, you will need one for each
installation of the MySQL software. This covers any number of CPUs on a
machine, and there is no artificial limit on the number of clients that
connect to the server in any way.

For commercial licenses, please visit our Web site at
`http://www.mysql.com/products/licensing/'.  For support contracts, see
`http://www.mysql.com/support/'.  If you have special needs, please
contact our sales staff via email at <[e-mail]>.

Using the MySQL Software for Free Under GPL
...........................................

You can use the MySQL software for free under the GPL if you adhere to
the conditions of the GPL.  For additional details about the GPL,
including answers to common questions, see the generic FAQ from the
Free Software Foundation at `http://www.fsf.org/licenses/gpl-faq.html'.

Our GPL licensing is supported by an optional license exception that
enables many Free/Libre and Open Source Software ("FLOSS") applications
to include the GPL-licensed MySQL client libraries despite the fact
that not all FLOSS licenses are compatible with the GPL. For details,
see `http://www.mysql.com/products/licensing/foss-exception.html'.

Common uses of the GPL include:

   * When you distribute both your own application and the MySQL source
     code under the GPL with your product.

   * When you distribute the MySQL source code bundled with other
     programs that are not linked to or dependent on the MySQL system
     for their functionality even if you sell the distribution
     commercially.  This is called "mere aggregation" in the GPL
     license.

   * When you are not distributing _any_ part of the MySQL system, you
     can use it for free.

   * When you are an Internet Service Provider (ISP), offering Web
     hosting with MySQL servers for your customers.  We encourage
     people to use ISPs that have MySQL support, because doing so will
     give them the confidence that their ISP will, in fact, have the
     resources to solve any problems they may experience with the MySQL
     installation. Even if an ISP does not have a commercial license
     for MySQL Server, their customers should at least be given read
     access to the source of the MySQL installation so that the
     customers can verify that it is correctly patched.

   * When you use the MySQL database software in conjunction with a Web
     server, you do not need a commercial license (so long as it is not
     a product you distribute). This is true even if you run a
     commercial Web server that uses MySQL Server, because you are not
     distributing any part of the MySQL system. However, in this case
     we would like you to purchase MySQL support because the MySQL
     software is helping your enterprise.

If your use of MySQL database software does not require a commercial
license, we encourage you to purchase support from MySQL AB anyway.
This way you contribute toward MySQL development and also gain
immediate advantages for yourself. *Note Support::.

If you use the MySQL database software in a commercial context such
that you profit by its use, we ask that you further the development of
the MySQL software by purchasing some level of support.  We feel that
if the MySQL database helps your business, it is reasonable to ask that
you help MySQL AB.  (Otherwise, if you ask us support questions, you
are not only using for free something into which we've put a lot a
work, you're asking us to provide free support, too.)

MySQL AB Logos and Trademarks
-----------------------------

Many users of the MySQL database want to display the MySQL AB dolphin
logo on their Web sites, books, or boxed products. We welcome and
encourage this, although it should be noted that the word MySQL and the
MySQL dolphin logo are (registered) trademarks of MySQL AB and may only
be used as stated in our trademark policy at
`http://www.mysql.com/company/trademark.html'.

The Original MySQL Logo
.......................

The MySQL dolphin logo was designed by the Finnish advertising agency
Priority in 2001.  The dolphin was chosen as a suitable symbol for the
MySQL database management system, which is like a smart, fast, and lean
animal, effortlessly navigating oceans of data. We also happen to like
dolphins.

The original MySQL logo may only be used by representatives of MySQL AB
and by those having a written agreement allowing them to do so.

MySQL Logos That May Be Used Without Written Permission
.......................................................

We have designed a set of special _Conditional Use_ logos that may be
downloaded from our Web site at `http://www.mysql.com/press/logos.html'
and used on third-party Web sites without written permission from MySQL
AB.  The use of these logos is not entirely unrestricted but, as the
name implies, subject to our trademark policy that is also available on
our Web site. You should read through the trademark policy if you plan
to use them. The requirements are basically as follows:

   * Use the logo you need as displayed on the `http://www.mysql.com/'
     site. You may scale it to fit your needs, but may not change
     colors or design, or alter the graphics in any way.

   * Make it evident that you, and not MySQL AB, are the creator and
     owner of the site that displays the MySQL (registered) trademark.

   * Don't use the trademark in a way that is detrimental to MySQL AB
     or to the value of MySQL AB trademarks. We reserve the right to
     revoke the right to use the MySQL AB trademark.

   * If you use the trademark on a Web site, make it clickable, leading
     directly to `http://www.mysql.com/'.

   * If you use the MySQL database under GPL in an application, your
     application must be Open Source and must be able to connect to a
     MySQL server.

Contact us via email at <[e-mail]> to inquire about special
arrangements to fit your needs.

When You Need Written Permission to Use MySQL Logos
...................................................

You need written permission from MySQL AB before using MySQL logos in
the following cases:

   * When displaying any MySQL AB logo anywhere except on your Web site.

   * When displaying any MySQL AB logo except the _Conditional Use_
     logos (mentioned previously) on Web sites or elsewhere.

Due to legal and commercial reasons, we monitor the use of MySQL
(registered) trademarks on products, books, and other items.  We
usually require a fee for displaying MySQL AB logos on commercial
products, since we think it is reasonable that some of the revenue is
returned to fund further development of the MySQL database.

MySQL AB Partnership Logos
..........................

MySQL partnership logos may be used only by companies and persons
having a written partnership agreement with MySQL AB. Partnerships
include certification as a MySQL trainer or consultant.  For more
information, please see *Note Partnering: Business Services Partnering.

Using the Word MySQL in Printed Text or Presentations
.....................................................

MySQL AB welcomes references to the MySQL database, but it should be
noted that the word MySQL is a registered trademark of MySQL AB.
Because of this, you must append the "registered trademark" notice
symbol (`R') to the first or most prominent use of the word MySQL in a
text and, where appropriate, state that MySQL is a registered trademark
of MySQL AB. For more information, please refer to our trademark policy
at `http://www.mysql.com/company/trademark.html'.

Using the Word MySQL in Company and Product Names
.................................................

Use of the word MySQL in company or product names or in Internet domain
names is not allowed without written permission from MySQL AB.
`http://www.mysql.com/company/contact/'.

MySQL Development Roadmap
=========================

This section provides a snapshot of the MySQL development roadmap,
including major features implemented or planned for MySQL 4.0, 4.1,
5.0, and 5.1.  The following sections provide information for each
release series.

The production release series is MySQL 4.0, which was declared stable
for production use as of Version 4.0.12, released in March 2003. This
means that future 4.0 development is limited only to bugfixes.  For the
older MySQL 3.23 series, only critical bugfixes are made.

4.1 is available in gamma status and will soon move to production stage.

Active MySQL development currently is taking place in the MySQL 5.0
release series, this means that new features are being added there.
MySQL 5.0 is available in alpha status.

Before upgrading from one release series to the next, please see the
notes at *Note Upgrade::.

Plans for some of the most requested features are summarized in the
following table.

*Feature*              *MySQL Series*
Unions                 4.0
Subqueries             4.1
R-trees                4.1 (for `MyISAM' tables)
Stored procedures      5.0
Views                  5.0
Cursors                5.0
Foreign keys           5.1 (already implemented in 3.23 for
                       `InnoDB')
Triggers               5.0 and 5.1
Full outer join        5.1
Constraints            5.1

MySQL 4.0 in a Nutshell
-----------------------

MySQL Server 4.0 is available in production status.

MySQL 4.0 is available for download at `http://dev.mysql.com/' and from
our mirrors. MySQL 4.0 has been tested by a large number of users and
is in production use at many large sites.

The major new features of MySQL Server 4.0 are geared toward our
existing business and community users, enhancing the MySQL database
software as the solution for mission-critical, heavy-load database
systems.  Other new features target the users of embedded databases.

Features Available in MySQL 4.0
...............................

Speed enhancements
        * MySQL 4.0 has a query cache that can give a huge speed boost
          to applications with repetitive queries. *Note Query Cache::.

        * Version 4.0 further increases the speed of MySQL Server in a
          number of areas, such as bulk `INSERT' statements, searching
          on packed indexes, full-text searching (using `FULLTEXT'
          indexes), and `COUNT(DISTINCT)'.

Embedded MySQL Server introduced
        * The new Embedded Server library can easily be used to create
          standalone and embedded applications.  The embedded server
          provides an alternative to using MySQL in a client/server
          environment.  *Note Nutshell Embedded MySQL::.

`InnoDB' storage engine as standard
        * The `InnoDB' storage engine is offered as a standard feature
          of the MySQL server. This means full support for ACID
          transactions, foreign keys with cascading `UPDATE' and
          `DELETE', and row-level locking are now standard features.
          *Note `InnoDB': InnoDB.

New functionality
        * The enhanced `FULLTEXT' search properties of MySQL Server 4.0
          enables `FULLTEXT' indexing of large text masses with both
          binary and natural-language searching logic. You can
          customize minimal word length and define your own stop word
          lists in any human language, enabling a new set of
          applications to be built with MySQL Server.  *Note Fulltext
          Search::.

Standards compliance, portability, and migration
        * Many users will also be happy to learn that MySQL Server now
          supports the `UNION' statement, a long-awaited standard SQL
          feature.

        * MySQL runs natively on the Novell NetWare platform beginning
          with NetWare 6.0.  *Note NetWare installation::.

        * Features to simplify migration from other database systems to
          MySQL Server include `TRUNCATE TABLE' (as in Oracle).

Internationalization
        * Our German, Austrian, and Swiss users will note that MySQL
          4.0 now supports a new character set, `latin1_de', which
          ensures that the _German sorting order_ sorts words with
          umlauts in the same order as do German telephone books.

Usability enhancements
     In the process of implementing features for new users, we have not
     forgotten requests from our loyal community of existing users.

        * Most `mysqld' parameters (startup options) can be set without
          taking down the server. This is a convenient feature for
          database administrators (DBAs).  *Note `SET OPTION': SET
          OPTION.

        * Multiple-table `DELETE' and `UPDATE' statements have been
          added.

        * On Windows, symbolic link handling at the database level is
          enabled by default.  On Unix, the `MyISAM' storage engine
          supports symbolic linking at the table level (and not just
          the database level as before).

        * `SQL_CALC_FOUND_ROWS' and `FOUND_ROWS()' are new functions
          that make it possible to find out the number of rows a
          `SELECT' query that includes a `LIMIT' clause would have
          returned without that clause.

The news section of this manual includes a more in-depth list of
features.  *Note News-4.0.x::.

The Embedded MySQL Server
.........................

The `libmysqld' embedded server library makes MySQL Server suitable for
a vastly expanded realm of applications. By using this library,
developers can embed MySQL Server into various applications and
electronics devices, where the end user has no knowledge of there
actually being an underlying database. Embedded MySQL Server is ideal
for use behind the scenes in Internet appliances, public kiosks, turnkey
hardware/software combination units, high performance Internet servers,
self-contained databases distributed on CD-ROM, and so on.

Many users of `libmysqld' will benefit from the MySQL Dual Licensing.
For those not wishing to be bound by the GPL, the software is also made
available under a commercial license.  The embedded MySQL library uses
the same interface as the normal client library, so it is convenient
and easy to use.  *Note `libmysqld': libmysqld.

On windows there are two different libraries:

`libmysqld.lib'        Dynamic library for threaded applications.
`mysqldemb.lib'        Static library for not threaded
                       applications.

MySQL 4.1 in a Nutshell
-----------------------

MySQL Server 4.0 laid the foundation for new features implemented in
MySQL 4.1, such as subqueries and Unicode support, and for the work on
stored procedures being done in version 5.0.  These features come at
the top of the wish list of many of our customers.  Already well-known
for its stability, speed, and ease of use, MySQL Server is now able to
fulfill the requirement checklists of very demanding buyers.

MySQL 4.1 is now available in gamma status, and will be production soon.

Features Available in MySQL 4.1
...............................

This section lists features implemented in MySQL 4.1.

New features currently being coded are or will be available in MySQL
5.0.  *Note TODO MySQL 5.0::.

Support for subqueries and derived tables
        * A "subquery" is a `SELECT' statement nested within another
          statement.  A "derived table" (an unnamed view) is a subquery
          in the `FROM' clause of another statement.  *Note
          Subqueries::.

Speed enhancements
        * Faster binary client/server protocol with support for
          prepared statements and parameter binding.  *Note C API
          Prepared statements::.

        * `BTREE' indexing is supported for `HEAP' tables,
          significantly improving response time for non-exact searches.

New functionality
        * `CREATE TABLE TBL_NAME2 LIKE TBL_NAME1' allows you to create,
          with a single statement, a new table with a structure exactly
          like that of an existing table.

        * The `MyISAM' storage engine supports OpenGIS spatial types
          for storing geographical data.  *Note Spatial extensions in
          MySQL::.

        * Replication can be done over SSL connections.

Standards compliance, portability, and migration
        * The new client/server protocol adds the ability to pass
          multiple warnings to the client, rather than only a single
          result. This makes it much easier to track problems that
          occur in operations such as bulk data loading.

        * `SHOW WARNINGS' shows warnings for the last command.  *Note
          `SHOW WARNINGS': SHOW WARNINGS.

Internationalization and Localization
        * To support applications that require the use of local
          languages, the MySQL software offers extensive Unicode
          support through the `utf8' and `ucs2' character sets.

        * Character sets can be defined per column, table, and database.
          This allows for a high degree of flexibility in application
          design, particularly for multi-language Web sites.

        * For documentation for this improved character set support,
          see *Note Charset::.

        * Per-connection time zones are supported, allowing individual
          clients to select their own time zone when necessary.

Usability enhancements
        * In response to popular demand, we have added a server-based
          `HELP' command that can be used to get help information for
          SQL statements.  The advantage of having this information on
          the server side is that the information is always applicable
          to the particular server version that you actually are using.
          Because this information is available by issuing an SQL
          statement, any client can be written to access it.  For
          example, the `help' command of the `mysql' command-line client
          has been modified to have this capability.

        * In the new client/server protocol, multiple statements can be
          issued with a single call.  *Note C API multiple queries::.

        * The new client/server protocol also supports returning
          multiple result sets.  This might occur as a result of
          sending multiple statements, for example.

        * A new `INSERT ... ON DUPLICATE KEY UPDATE ...' syntax has been
          implemented. This allows you to `UPDATE' an existing row if
          the `INSERT' would have caused a duplicate in a `PRIMARY' or
          `UNIQUE' index.  *Note `INSERT': INSERT.

        * A new aggregate function, `GROUP_CONCAT()' adds the extremely
          useful capability of concatenating column values from grouped
          rows into a single result string.  *Note Group by functions
          and modifiers::.

The news section of this manual includes a more in-depth list of
features.  *Note News-4.1.x::.

Stepwise Rollout
................

The gamma version of MySQL 4.1 is available for download.  *Note
Nutshell Ready for Immediate Use::.

MySQL 4.1 is currently in the _Gamma_ stage (indicating that a
production release is just weeks ahead).  At the end of this process,
MySQL 4.1 will become the new production release.

Development is already ongoing for version 5.0.

Ready for Immediate Development Use
...................................

MySQL 4.1 is currently in the gamma stage, and binaries are available
for download at `http://dev.mysql.com/downloads/mysql/4.1.html'.  All
binary releases pass our extensive test suite without any errors on the
platforms on which we test.  *Note News-4.1.x::.

For those wishing to use the most recent development source for MySQL
4.1, we also make our BitKeeper repositories publicly available.  *Note
Installing source tree::.

MySQL 5.0: The Next Development Release
---------------------------------------

New development for MySQL is focused on the 5.0 release, featuring
stored procedures, updatable views, rudimentary triggers, and other new
features.  *Note TODO MySQL 5.0::.

For those wishing to take a look at the bleeding edge of MySQL
development, we make our BitKeeper repository for MySQL version 5.0
publicly available.  *Note Installing source tree::.  As of December
2003, binary builds of version 5.0 have also been available.

MySQL and the Future (the TODO)
===============================

This section summarizes the features that we plan to implement in MySQL
Server. The items are ordered by release series. Within a list, items
are shown in approximately the order they will be done.

*Note*: If you are an enterprise-level user with an urgent need for a
particular feature, please contact <[e-mail]> to discuss
sponsoring options. Targeted financing by sponsor companies allows us
to allocate additional resources for specific purposes.  One example of
a feature sponsored in the past is replication.

New Features Planned for 5.0
----------------------------

The following features are planned for inclusion into MySQL 5.0.  Some
of the features such as stored procedures are complete and are included
in MySQL 5.0 alpha, which is available now.  Others such as cursors are
only partially available. Expect these and other features to mature and
be fully supported in upcoming releases.

Note that because we have many developers that are working on different
projects, there will also be many additional features. There is also a
small chance that some of these features will be added to MySQL 4.1.
For a list what is already done in MySQL 4.1, see *Note Nutshell 4.1
features::.

For those wishing to take a look at the bleeding edge of MySQL
development, we make our BitKeeper repository for MySQL version 5.0
publicly available.  *Note Installing source tree::.  As of December
2003, binary builds of version 5.0 are also available.

Views
        * Views, implemented in stepwise fashion up to full
          functionality.  *Note ANSI diff Views::. *Note CREATE VIEW::.

Stored Procedures
        * Stored procedures currently are implemented, based on the
          SQL:2003 standard.  *Note Stored Procedures::.


New functionality
        * Elementary cursor support.  *Note Cursors::.

        * The ability to specify explicitly for `MyISAM' tables that an
          index should be created as an `RTREE' index.  (In MySQL 4.1,
          `RTREE' indexes are used internally for geometrical data that
          use GIS data types, but cannot be created on request.)

        * Dynamic length rows for `MEMORY' tables.

Standards compliance, portability and migration
        * Support for Data Dictionary / `INFORMATION_SCHEMA'.

        * Add true `VARCHAR' support (column lengths longer than 255,
          and no stripping of trailing whitespace).  There is already
          support for this in the `MyISAM' storage engine, but it is
          not yet available at the user level.

Speed enhancements
        * `SHOW COLUMNS FROM TBL_NAME' (used by the `mysql' client to
          allow expansions of column names) should not open the table,
          only the definition file. This will require less memory and
          be much faster.

        * Allow `DELETE' on `MyISAM' tables to use the record cache.
          To do this, we need to update the threads record cache when
          we update the `.MYD' file.

        * Better support for `MEMORY' tables:
             * Dynamic length rows.

             * Faster row handling (less copying).

Usability enhancements
        * Resolving the issue of `RENAME TABLE' on a table used in an
          active `MERGE' table possibly corrupting the table.

The news section of this manual includes a more in-depth list of
features.  *Note News-5.0.x::.

New Features Planned for 5.1
----------------------------

New functionality
        * `FOREIGN KEY' support for all table types, not just `InnoDB'.

        * Column-level constraints.  *Note Constraints::.

        * Online backup with very low performance penalty.  The online
          backup will make it easy to add a new replication slave
          without taking down the master.

Speed enhancements
        * New text based table definition file format (`.frm' files)
          and a table cache for table definitions.  This will enable us
          to do faster queries of table structures and do more
          efficient foreign key support.

        * Optimize the `BIT' type to take one bit. (`BIT' now takes one
          byte; it is treated as a synonym for `TINYINT'.)

Usability enhancements
        * Add options to the client/server protocol to get progress
          notes for long running commands.

        * Implement `RENAME DATABASE'. To make this safe for all
          storage engines, it should work as follows:
            1. Create the new database.

            2. For every table, do a rename of the table to another
               database, as we do with the `RENAME' command.

            3. Drop the old database.

        * New internal file interface change.  This will make all file
          handling much more general and make it easier to add
          extensions like RAID.

New Features Planned for the Near Future
----------------------------------------

New functionality
        * Oracle-like `CONNECT BY PRIOR' to search tree-like
          (hierarchical) structures.

        * Add all missing standard SQL and ODBC 3.0 types.

        * Add `SUM(DISTINCT)'.

        * `INSERT SQL_CONCURRENT' and `mysqld --concurrent-insert' to do
          a concurrent insert at the end of a table if the table is
          read-locked.

        * Allow variables to be updated in `UPDATE' statements. For
          example: `UPDATE foo SET @a:=a+b,a=@a, b=@a+c'.

        * Change when user variables are updated so that you can use
          them with `GROUP BY', as in the following statement: `SELECT
          id, @a:=COUNT(*), SUM(SUM_COL)/@a FROM TBL_NAME GROUP BY id'.

        * Add an `IMAGE' option to `LOAD DATA INFILE' to not update
          `TIMESTAMP' and `AUTO_INCREMENT' columns.

        * Add `LOAD DATA INFILE ... UPDATE' syntax that works like this:
             * For tables with primary keys, if an input record
               contains a primary key value, existing rows matching
               that primary key value are updated from the remainder of
               the input columns. However, columns corresponding to
               columns that are _missing_ from the input record are not
               touched.

             * For tables with primary keys, if an input record does
               not contain the primary key value or is missing some
               part of the key, the record is treated as `LOAD DATA
               INFILE ... REPLACE INTO'.

        * Make `LOAD DATA INFILE' understand syntax like this:
               LOAD DATA INFILE 'FILE_NAME.txt' INTO TABLE TBL_NAME
                    TEXT_FIELDS (text_col1, text_col2, text_col3)
                    SET table_col1=CONCAT(text_col1, text_col2),
                        table_col3=23
                    IGNORE text_col3
          This can be used to skip over extra columns in the text file,
          or update columns based on expressions of the read data.

        * New functions for working with `SET' type columns:
             * `ADD_TO_SET(VALUE,SET)'

             * `REMOVE_FROM_SET(VALUE,SET)'

        * If you abort `mysql' in the middle of a query, you should open
          another connection and kill the old running query.
          Alternatively, an attempt should be made to detect this in
          the server.

        * Add a storage engine interface for table information so that
          you can use it as a system table. This would be a bit slow if
          you requested information about all tables, but very
          flexible.  `SHOW INFO FROM TBL_NAME' for basic table
          information should be implemented.

        * Allow `SELECT a FROM TBL_NAME1 LEFT JOIN TBL_NAME2 USING
          (a)'; in this case `a' is assumed to come from TBL_NAME1.

        * `DELETE' and `REPLACE' options to the `UPDATE' statement
          (this will delete rows when a duplicate-key error occurs
          while updating).

        * Change the format of `DATETIME' to store fractions of seconds.

        * Make it possible to use the new GNU `regexp' library instead
          of the current one (the new library should be much faster
          than the current one).

Standards compliance, portability and migration
        * Add `ANY()', `EVERY()', and `SOME()' group functions. In
          standard SQL, these work only on boolean columns, but we can
          extend these to work on any columns or expressions by
          treating a value of zero as FALSE and non-zero values as TRUE.

        * Fix the type of `MAX(column)' to be the same as the column
          type:
               mysql> CREATE TABLE t1 (a DATE);
               mysql> INSERT INTO t1 VALUES (NOW());
               mysql> CREATE TABLE t2 SELECT MAX(a) FROM t1;
               mysql> SHOW COLUMNS FROM t2;

Speed enhancements
        * Don't allow more than a defined number of threads to run
          `MyISAM' recovery at the same time.

        * Change `INSERT INTO ... SELECT' to optionally use concurrent
          inserts.

        * Add an option to periodically flush key pages for tables with
          delayed keys if they haven't been used in a while.

        * Allow join on key parts (optimization issue).

        * Add a log file analyzer that can extract information about
          which tables are hit most often, how often multiple-table
          joins are executed, and so on. This should help users
          identify areas of table design that could be optimized to
          execute much more efficient queries.

Usability enhancements
        * Return the original column types when doing `SELECT
          MIN(column) ... GROUP BY'.

        * Make it possible to specify `long_query_time' with a
          granularity in microseconds.

        * Link the `myisampack' code into the server so that it can
          perform `PACK' or `COMPRESS' operations.

        * Add a temporary key buffer cache during
          `INSERT/DELETE/UPDATE' so that we can gracefully recover if
          the index file gets full.

        * If you perform an `ALTER TABLE' on a table that is symlinked
          to another disk, create temporary tables on that disk.

        * Implement a `DATE/DATETIME' type that handles time zone
          information properly, to make dealing with dates in different
          time zones easier.

        * Fix `configure' so that all libraries (like `MyISAM') can be
          compiled without threads.

        * Allow user variables as `LIMIT' arguments; for example,
          `LIMIT @a,@b'.

        * Automatic output from `mysql' to a Web browser.

        * `LOCK DATABASES' (with various options).

        * Many more variables for `SHOW STATUS'.  Record reads and
          updates.  Selects on a single table and selects with joins.
          Mean number of tables in selects. Number of `ORDER BY' and
          `GROUP BY' queries.

        * `mysqladmin copy database new-database'; this requires a
          `COPY' operation to be added to `mysqld'.

        * Processlist output should indicate the number of
          queries/threads.

        * `SHOW HOSTS' for printing information about the hostname
          cache.

        * Change table names from empty strings to `NULL' for
          calculated columns.

        * Don't use `Item_copy_string' on numerical values to avoid
          number-to-string-to-number conversion in case of `SELECT
          COUNT(*)*(id+0) FROM TBL_NAME GROUP BY id'.

        * Change so that `ALTER TABLE' doesn't abort clients that
          execute `INSERT DELAYED'.

        * Fix so that when columns are referenced in an `UPDATE' clause,
          they contain the old values from before the update started.

New operating systems
        * Port the MySQL clients to LynxOS.

New Features Planned for the Mid-Term Future
--------------------------------------------

   * Implement function:
     `get_changed_tables(timeout,table1,table2,...)'.

   * Change reading through tables to use `mmap()' when possible. Now
     only compressed tables use `mmap()'.

   * Make the automatic timestamp code nicer.  Add timestamps to the
     update log with `SET TIMESTAMP=val;'.

   * Use read/write mutex in some places to get more speed.

   * Automatically close some tables if a table, temporary table, or
     temporary file gets error 23 (too many open files).

   * Better constant propagation. When an occurrence of COL_NAME=N is
     found in an expression, for some constant `n', replace other
     occurrences of COL_NAME within the expression with `n'.
     Currently, this is done only for some simple cases.

   * Change all const expressions with calculated expressions if
     possible.

   * Optimize KEY = EXPR comparisons. At the moment, only KEY = COLUMN
     or KEY = CONSTANT comparisons are optimized.

   * Join some of the copy functions for nicer code.

   * Change `sql_yacc.yy' to an inline parser to reduce its size and get
     better error messages.

   * Change the parser to use only one rule per different number of
     arguments in function.

   * Use of full calculation names in the order part (for Access97).

   * `MINUS', `INTERSECT', and `FULL OUTER JOIN'.  (Currently `UNION'
     and `LEFT|RIGHT OUTER JOIN' are supported.)

   * Allow `SQL_OPTION MAX_SELECT_TIME=val', for placing a time limit
     on a query.

   * Allow updates to be logged to a database.

   * Enhance `LIMIT' to allow retrieval of data from the end of a
     result set.

   * Alarm around client connect/read/write functions.

   * Please note the changes to `mysqld_safe': According to FSSTND
     (which Debian tries to follow), PID files should go into
     `/var/run/<progname>.pid' and log files into `/var/log'. It would
     be nice if you could put the "DATADIR" in the first declaration of
     "pidfile" and "log" so that the placement of these files can be
     changed with a single statement.

   * Allow a client to request logging.

   * Allow the `LOAD DATA INFILE' statement to read files that have
     been compressed with `gzip'.

   * Fix sorting and grouping of `BLOB' columns (partly solved now).

   * Change to use semaphores when counting threads.  One should first
     implement a semaphore library for MIT-pthreads.

   * Add full support for `JOIN' with parentheses.

   * As an alternative to the one-thread-per-connection model, manage a
     pool of threads to handle queries.

   * Allow `GET_LOCK()' to obtain more than one lock.  When doing this,
     it is also necessary to handle the possible deadlocks this change
     will introduce.

New Features We Don't Plan to Implement
---------------------------------------

We aim toward full compliance with ANSI/ISO SQL. There are no features
we plan not to implement.

MySQL Information Sources
=========================

MySQL Mailing Lists
-------------------

This section introduces the MySQL mailing lists and provides guidelines
as to how the lists should be used. When you subscribe to a mailing
list, you will receive all postings to the list as email messages. You
can also send your own questions and answers to the list.

The MySQL Mailing Lists
.......................

To subscribe to or unsubscribe from any of the mailing lists described
in this section, visit `http://lists.mysql.com/'. For most of them, you
can select the regular version of the list where you get individual
messages, or a digest version where you get one large message per day.

Please _do not_ send messages about subscribing or unsubscribing to any
of the mailing lists, because such messages are distributed
automatically to thousands of other users.

Your local site may have many subscribers to a MySQL mailing list.  If
so, the site may have a local mailing list, so that messages sent from
`lists.mysql.com' to your site are propagated to the local list.  In
such cases, please contact your system administrator to be added to or
dropped from the local MySQL list.

If you wish to have traffic for a mailing list go to a separate mailbox
in your mail program, set up a filter based on the message headers.
You can use either the `List-ID:' or `Delivered-To:' headers to identify
list messages.

The MySQL mailing lists are as follows:

`announce'
     This list is for announcements of new versions of MySQL and related
     programs.  This is a low-volume list to which all MySQL users
     should subscribe.

`mysql'
     This is the main list for general MySQL discussion.  Please note
     that some topics are better discussed on the more-specialized
     lists.  If you post to the wrong list, you may not get an answer.

`bugs'
     This list will be of interest to you if you want to stay informed
     about issues reported since the last release of MySQL or if you
     want to be actively involved in the process of bug hunting and
     fixing.  *Note Bug reports::.

`internals'
     This list is for people who work on the MySQL code.  This is also
     the forum for discussions on MySQL development and for posting
     patches.

`mysqldoc'
     This list is for people who work on the MySQL documentation:
     people from MySQL AB, translators, and other community members.

`benchmarks'
     This list is for anyone interested in performance issues.
     Discussions concentrate on database performance (not limited to
     MySQL), but also include broader categories such as performance of
     the kernel, filesystem, disk system, and so on.

`packagers'
     This list is for discussions on packaging and distributing MySQL.
     This is the forum used by distribution maintainers to exchange
     ideas on packaging MySQL and on ensuring that MySQL looks and
     feels as similar as possible on all supported platforms and
     operating systems.

`java'
     This list is for discussions about the MySQL server and Java. It
     is mostly used to discuss JDBC drivers, including MySQL
     Connector/J.

`win32'
     This list is for all topics concerning the MySQL software on
     Microsoft operating systems, such as Windows 9x, Me, NT, 2000, and
     XP.

`myodbc'
     This list is for all topics concerning connecting to the MySQL
     server with ODBC.

`gui-tools'
     This list is for all topics concerning MySQL GUI tools, including
     `MySQL Administrator' and the `MySQL Control Center' graphical
     client.

`cluster'
     This list is for discussion of MySQL Cluster.

`dotnet'
     This list is for discussion of the MySQL server and the .NET
     platform.  Mostly related to the MySQL Connector/Net provider.

`plusplus'
     This list is for all topics concerning programming with the C++
     API for MySQL.

`perl'
     This list is for all topics concerning the Perl support for MySQL
     with `DBD::mysql'.

If you're unable to get an answer to your questions from a MySQL mailing
list, one option is to purchase support from MySQL AB. This will put you
in direct contact with MySQL developers. *Note Support::.

The following table shows some MySQL mailing lists in languages other
than English.  These lists are not operated by MySQL AB.

`<[e-mail]>'
     A French mailing list.

`<[e-mail]>'
     A Korean mailing list.  Email `subscribe mysql [e-mail]'
     to this list.

`<[e-mail]>'
     A German mailing list.  Email `subscribe mysql-de
     [e-mail]' to this list.  You can find information about
     this mailing list at `http://www.4t2.com/mysql/'.

`<[e-mail]>'
     A Portuguese mailing list.  Email `subscribe mysql-br
     [e-mail]' to this list.

`<[e-mail]>'
     A Spanish mailing list.  Email `subscribe mysql
     [e-mail]' to this list.

Asking Questions or Reporting Bugs
..................................

Before posting a bug report or question, please do the following:

   * Start by searching the MySQL online manual at
     `http://dev.mysql.com/doc/'.  We try to keep the manual up to date
     by updating it frequently with solutions to newly found problems.
     The change history (`http://dev.mysql.com/doc/mysql/en/News.html')
     can be particularly useful since it is quite possible that a newer
     version already contains a solution to your problem.

   * Search in the bugs database at `http://bugs.mysql.com/' to see
     whether the bug has already been reported and fixed.

   * Search the MySQL mailing list archives at
     `http://lists.mysql.com/'.

   * You can also use `http://www.mysql.com/search/' to search all the
     Web pages (including the manual) that are located at the MySQL AB
     Web site.

If you can't find an answer in the manual or the archives, check with
your local MySQL expert.  If you still can't find an answer to your
question, please follow the guidelines on sending mail to a MySQL
mailing list, outlined in the next section, before contacting us.

How to Report Bugs or Problems
..............................

The normal place to report bugs is `http://bugs.mysql.com/', which is
the address for our bugs database.  This database is public, and can be
browsed and searched by anyone.  If you log in to the system, you will
also be able to enter new reports.

Writing a good bug report takes patience, but doing it right the first
time saves time both for us and for yourself.  A good bug report,
containing a full test case for the bug, makes it very likely that we
will fix the bug in the next release.  This section will help you write
your report correctly so that you don't waste your time doing things
that may not help us much or at all.

We encourage everyone to use the `mysqlbug' script to generate a bug
report (or a report about any problem).  `mysqlbug' can be found in the
`scripts' directory (source distribution) and in the `bin' directory
under your MySQL installation directory (binary distribution).  If you
are unable to use `mysqlbug' (for example, if you are running on
Windows), it is still vital that you include all the necessary
information noted in this section (most importantly, a description of
the operating system and the MySQL version).

The `mysqlbug' script helps you generate a report by determining much
of the following information automatically, but if something important
is missing, please include it with your message.  Please read this
section carefully and make sure that all the information described here
is included in your report.

Preferably, you should test the problem using the latest production or
development version of MySQL Server before posting.  Anyone should be
able to repeat the bug by just using `mysql test < script_file' on the
included test case or by running the shell or Perl script that is
included in the bug report.

All bugs posted in the bugs database at `http://bugs.mysql.com/' will
be corrected or documented in the next MySQL release. If only minor
code changes are needed to correct a problem, we may also post a patch
that fixes the problem.

If you have found a sensitive security bug in MySQL, you can send email
to <[e-mail]>.

If you have a repeatable bug report, please report it to the bugs
database at `http://bugs.mysql.com/'.  Note that even in this case it's
good to run the `mysqlbug' script first to find information about your
system.  Any bug that we are able to repeat has a high chance of being
fixed in the next MySQL release.

To report other problems, you can use one of the MySQL mailing lists.

Remember that it is possible for us to respond to a message containing
too much information, but not to one containing too little.  People
often omit facts because they think they know the cause of a problem
and assume that some details don't matter.  A good principle is this:
If you are in doubt about stating something, state it.  It is faster
and less troublesome to write a couple more lines in your report than
to wait longer for the answer if we must ask you to provide information
that was missing from the initial report.

The most common errors made in bug reports are (a) not including the
version number of the MySQL distribution used, and (b) not fully
describing the platform on which the MySQL server is installed
(including the platform type and version number).  This is highly
relevant information, and in 99 cases out of 100, the bug report is
useless without it.  Very often we get questions like, "Why doesn't
this work for me?" Then we find that the feature requested wasn't
implemented in that MySQL version, or that a bug described in a report
has already been fixed in newer MySQL versions.  Sometimes the error is
platform-dependent; in such cases, it is next to impossible for us to
fix anything without knowing the operating system and the version
number of the platform.

If you compiled MySQL from source, remember also to provide information
about your compiler, if it is related to the problem.  Often people
find bugs in compilers and think the problem is MySQL-related.  Most
compilers are under development all the time and become better version
by version.  To determine whether your problem depends on your
compiler, we need to know what compiler you use.  Note that every
compiling problem should be regarded as a bug and reported accordingly.

It is most helpful when a good description of the problem is included
in the bug report.  That is, give a good example of everything you did
that led to the problem and describe, in exact detail, the problem
itself.  The best reports are those that include a full example showing
how to reproduce the bug or problem.  *Note Reproduceable test case::.

If a program produces an error message, it is very important to include
the message in your report.  If we try to search for something from the
archives using programs, it is better that the error message reported
exactly matches the one that the program produces.  (Even the
lettercase should be observed.)  You should never try to reproduce from
memory what the error message was; instead, copy and paste the entire
message into your report.

If you have a problem with Connector/ODBC (MyODBC), please try to
generate a trace file and send it with your report.  *Note MyODBC bug
report::.

Please remember that many of the people who will read your report will
do so using an 80-column display.  When generating reports or examples
using the `mysql' command-line tool, you should therefore use the
`--vertical' option (or the `\G' statement terminator) for output that
would exceed the available width for such a display (for example, with
the `EXPLAIN SELECT' statement; see the example later in this section).

Please include the following information in your report:

   * The version number of the MySQL distribution you are using (for
     example, MySQL 4.0.12). You can find out which version you are
     running by executing `mysqladmin version'.  The `mysqladmin'
     program can be found in the `bin' directory under your MySQL
     installation directory.

   * The manufacturer and model of the machine on which you experience
     the problem.

   * The operating system name and version.  If you work with Windows,
     you can usually get the name and version number by double-clicking
     your My Computer icon and pulling down the "Help/About Windows"
     menu.  For most Unix-like operating systems, you can get this
     information by executing the command `uname -a'.

   * Sometimes the amount of memory (real and virtual) is relevant. If
     in doubt, include these values.

   * If you are using a source distribution of the MySQL software, the
     name and version number of the compiler used are needed.  If you
     have a binary distribution, the distribution name is needed.

   * If the problem occurs during compilation, include the exact error
     messages and also a few lines of context around the offending code
     in the file where the error occurs.

   * If `mysqld' died, you should also report the query that crashed
     `mysqld'.  You can usually find this out by running `mysqld' with
     query logging enabled, and then looking in the log after `mysqld'
     crashes *Note Using log files::.

   * If a database table is related to the problem, include the output
     from `mysqldump --no-data DB_NAME TBL_NAME'.  This is very easy to
     do and is a powerful way to get information about any table in a
     database.  The information will help us create a situation
     matching the one you have.

   * For speed-related bugs or problems with `SELECT' statements, you
     should always include the output of `EXPLAIN SELECT ...', and at
     least the number of rows that the `SELECT' statement produces.  You
     should also include the output from `SHOW CREATE TABLE TBL_NAME'
     for each involved table. The more information you give about your
     situation, the more likely it is that someone can help you.

     The following is an example of a very good bug report. It should
     be posted with the `mysqlbug' script.  The example uses the `mysql'
     command-line tool. Note the use of the `\G' statement terminator
     for statements whose output width would otherwise exceed that of
     an 80-column display device.

          mysql> SHOW VARIABLES;
          mysql> SHOW COLUMNS FROM ...\G
                 <output from SHOW COLUMNS>
          mysql> EXPLAIN SELECT ...\G
                 <output from EXPLAIN>
          mysql> FLUSH STATUS;
          mysql> SELECT ...;
                 <A short version of the output from SELECT,
                 including the time taken to run the query>
          mysql> SHOW STATUS;
                 <output from SHOW STATUS>

   * If a bug or problem occurs while running `mysqld', try to provide
     an input script that will reproduce the anomaly.  This script
     should include any necessary source files.  The more closely the
     script can reproduce your situation, the better.  If you can make
     a reproducible test case, you should post it on
     `http://bugs.mysql.com/' for high-priority treatment.

     If you can't provide a script, you should at least include the
     output from `mysqladmin variables extended-status processlist' in
     your mail to provide some information on how your system is
     performing.

   * If you can't produce a test case with only a few rows, or if the
     test table is too big to be mailed to the mailing list (more than
     10 rows), you should dump your tables using `mysqldump' and create
     a `README' file that describes your problem.

     Create a compressed archive of your files using `tar' and `gzip'
     or `zip', and use FTP to transfer the archive to
     `ftp://ftp.mysql.com/pub/mysql/upload/'.  Then enter the problem
     into our bugs database at `http://bugs.mysql.com/'.

   * If you think that the MySQL server produces a strange result from
     a query, include not only the result, but also your opinion of
     what the result should be, and an account describing the basis for
     your opinion.

   * When giving an example of the problem, it's better to use the
     variable names, table names, and so on that exist in your actual
     situation than to come up with new names.  The problem could be
     related to the name of a variable or table.  These cases are rare,
     perhaps, but it is better to be safe than sorry.  After all, it
     should be easier for you to provide an example that uses your
     actual situation, and it is by all means better for us.  In case
     you have data that you don't want to show to others, you can use
     FTP to transfer it to `ftp://ftp.mysql.com/pub/mysql/upload/'.  If
     the information is really top secret and you don't want to show it
     even to us, then go ahead and provide an example using other
     names, but please regard this as the last choice.

   * Include all the options given to the relevant programs, if
     possible.  For example, indicate the options that you use when you
     start the `mysqld' server as well as the options that you use to
     run any MySQL client programs.  The options to programs such as
     `mysqld' and `mysql', and to the `configure' script, are often
     keys to answers and are very relevant.  It is never a bad idea to
     include them.  If you use any modules, such as Perl or PHP, please
     include the version numbers of those as well.

   * If your question is related to the privilege system, please
     include the output of `mysqlaccess', the output of `mysqladmin
     reload', and all the error messages you get when trying to
     connect.  When you test your privileges, you should first run
     `mysqlaccess'.  After this, execute `mysqladmin reload version'
     and try to connect with the program that gives you trouble.
     `mysqlaccess' can be found in the `bin' directory under your MySQL
     installation directory.

   * If you have a patch for a bug, do include it.  But don't assume
     that the patch is all we need, or that we will use it, if you
     don't provide some necessary information such as test cases
     showing the bug that your patch fixes.  We might find problems
     with your patch or we might not understand it at all; if so, we
     can't use it.

     If we can't verify exactly what the purpose of the patch is, we
     won't use it.  Test cases will help us here.  Show that the patch
     will handle all the situations that may occur.  If we find a
     borderline case (even a rare one) where the patch won't work, it
     may be useless.

   * Guesses about what the bug is, why it occurs, or what it depends on
     are usually wrong.  Even the MySQL team can't guess such things
     without first using a debugger to determine the real cause of a
     bug.

   * Indicate in your bug report that you have checked the reference
     manual and mail archive so that others know you have tried to
     solve the problem yourself.

   * If you get a `parse error', please check your syntax closely.  If
     you can't find something wrong with it, it's extremely likely that
     your current version of MySQL Server doesn't support the syntax
     you are using.  If you are using the current version and the
     manual at `http://dev.mysql.com/doc/' doesn't cover the syntax you
     are using, MySQL Server doesn't support your query.  In this case,
     your only options are to implement the syntax yourself or email
     <[e-mail]> and ask for an offer to implement it.

     If the manual covers the syntax you are using, but you have an
     older version of MySQL Server, you should check the MySQL change
     history to see when the syntax was implemented.  In this case, you
     have the option of upgrading to a newer version of MySQL Server.
     *Note News::.

   * If your problem is that your data appears corrupt or you get errors
     when you access a particular table, you should first check and
     then try to repair your tables with `CHECK TABLE' and `REPAIR
     TABLE' or with `myisamchk'.  *Note MySQL Database Administration::.

     If you are running Windows, please verify that
     `lower_case_table_names' is 1 or 2 with `SHOW VARIABLES LIKE
     'lower_case_table_names''.

   * If you often get corrupted tables, you should try to find out when
     and why this happens.  In this case, the error log in the MySQL
     data directory may contain some information about what happened.
     (This is the file with the `.err' suffix in the name.)  *Note
     Error log::.  Please include any relevant information from this
     file in your bug report.  Normally `mysqld' should _never_ crash a
     table if nothing killed it in the middle of an update.  If you can
     find the cause of `mysqld' dying, it's much easier for us to
     provide you with a fix for the problem.  *Note What is crashing::.

   * If possible, download and install the most recent version of MySQL
     Server and check whether it solves your problem.  All versions of
     the MySQL software are thoroughly tested and should work without
     problems.  We believe in making everything as backward-compatible
     as possible, and you should be able to switch MySQL versions
     without difficulty.  *Note Which version::.

If you are a support customer, please cross-post the bug report to
<[e-mail]> for higher-priority treatment, as well as to
the appropriate mailing list to see whether someone else has
experienced (and perhaps solved) the problem.

For information on reporting bugs in MyODBC, see *Note MyODBC bug
report::.

For solutions to some common problems, see *Note Problems::.

When answers are sent to you individually and not to the mailing list,
it is considered good etiquette to summarize the answers and send the
summary to the mailing list so that others may have the benefit of
responses you received that helped you solve your problem.

Guidelines for Answering Questions on the Mailing List
......................................................

If you consider your answer to have broad interest, you may want to
post it to the mailing list instead of replying directly to the
individual who asked.  Try to make your answer general enough that
people other than the original poster may benefit from it.  When you
post to the list, please make sure that your answer is not a
duplication of a previous answer.

Try to summarize the essential part of the question in your reply;
don't feel obliged to quote the entire original message.

Please don't post mail messages from your browser with HTML mode turned
on.  Many users don't read mail with a browser.

MySQL Community Support on IRC (Internet Relay Chat)
----------------------------------------------------

In addition to the various MySQL mailing lists, you can find experienced
community people on `IRC' (`Internet Relay Chat').  These are the best
networks/channels currently known to us:

   * *freenode* (see `http://www.freenode.net/' for servers)
        * `#mysql' Primarily MySQL questions, but other database and
          general SQL questions are welcome.  Questions about PHP, Perl
          or C in combination with MySQL are also common.

   * *EFnet* (see `http://www.efnet.org/' for servers)
        * `#mysql' MySQL questions.

If you are looking for IRC client software to connect to an IRC network,
take a look at `X-Chat' (`http://www.xchat.org/').  X-Chat (GPL
licensed) is available for Unix as well as for Windows platforms.

MySQL Standards Compliance
==========================

This section describes how MySQL relates to the ANSI/ISO SQL standards.
MySQL Server has many extensions to the SQL standard, and here you will
find out what they are and how to use them.  You will also find
information about functionality missing from MySQL Server, and how to
work around some differences.

The SQL standard has been evolving since 1986 and several versions
exist. In this manual, "SQL-92" refers to the standard released in 1992,
"SQL:1999" refers to the standard released in 1999, and "SQL:2003"
refers to the current version of the standard.  We use the phrase "the
SQL standard" to mean the current version of the SQL Standard at any
time.

Our goal is to not restrict MySQL Server usability for any usage
without a very good reason for doing so.  Even if we don't have the
resources to perform  development for every possible use, we are always
willing to help and offer suggestions to people who are trying to use
MySQL Server in new territories.

One of our main goals with the product is to continue to work toward
compliance with the SQL standard, but without sacrificing speed or
reliability.  We are not afraid to add extensions to SQL or support for
non-SQL features if this greatly increases the usability of MySQL
Server for a large segment of our user base.  The `HANDLER' interface
in MySQL Server 4.0 is an example of this strategy. *Note `HANDLER':
HANDLER.

We will continue to support transactional and non-transactional
databases to satisfy both mission-critical 24/7 usage and heavy Web or
logging usage.

MySQL Server was originally designed to work with medium size databases
(10-100 million rows, or about 100MB per table) on small computer
systems.  Today MySQL Server handles terabyte-size databases, but the
code can also be compiled in a reduced version suitable for hand-held
and embedded devices.  The compact design of the MySQL server makes
development in both directions possible without any conflicts in the
source tree.

Currently, we are not targeting realtime support, although MySQL
replication capabilities already offer significant functionality.

Database cluster support now exists through third-party clustering
solutions as well as the integration of our acquired NDB Cluster
technology into a new storage engine, available from version 4.1.2.
*Note NDBCluster::.

We are also looking at providing XML support in the database server.

What Standards MySQL Follows
----------------------------

We are aiming toward supporting the full ANSI/ISO SQL standard, but
without making concessions to speed and quality of the code.

ODBC levels 0-3.51.

Selecting SQL Modes
-------------------

The MySQL server can operate in different SQL modes, and can apply these
modes differentially for different clients. This allows an application
to tailor server operation to its own requirements.

Modes define what SQL syntax MySQL should support and what kind of
validation checks it should perform on the data.  This makes it easier
to use MySQL in a lot of different environments and to use MySQL
together with other database servers.

You can set the default SQL mode by starting `mysqld' with the
`--sql-mode="modes"' option. Beginning with MySQL 4.1, you can also
change the mode after startup time by setting the `sql_mode' variable
with a `SET [SESSION|GLOBAL] sql_mode='modes'' statement.

For more information on setting the server mode, see *Note Server SQL
mode::.

Running MySQL in ANSI Mode
--------------------------

You can tell `mysqld' to use the ANSI mode with the `--ansi' startup
option. *Note Server options::.

Running the server in ANSI mode is the same as starting it with these
options (specify the `--sql_mode' value on a single line):

     --transaction-isolation=SERIALIZABLE
     --sql-mode=REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,
     IGNORE_SPACE,ONLY_FULL_GROUP_BY

In MySQL 4.1, you can achieve the same effect with these two statements
(specify the `sql_mode' value on a single line):

     SET GLOBAL TRANSACTION ISOLATION LEVEL SERIALIZABLE;
     SET GLOBAL sql_mode = 'REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,
     IGNORE_SPACE,ONLY_FULL_GROUP_BY';

*Note SQL mode::.

In MySQL 4.1.1, the `sql_mode' options shown can be also be set with
this statement:

     SET GLOBAL sql_mode='ansi';

In this case, the value of the `sql_mode' variable will be set to all
options that are relevant for ANSI mode. You can check the result like
this:

     mysql> SET GLOBAL sql_mode='ansi';
     mysql> SELECT @@global.sql_mode;
             -> 'REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,
                 IGNORE_SPACE,ONLY_FULL_GROUP_BY,ANSI';

MySQL Extensions to Standard SQL
--------------------------------

MySQL Server includes some extensions that you probably will not find in
other SQL databases.  Be warned that if you use them, your code will
not be portable to other SQL servers.  In some cases, you can write
code that includes MySQL extensions, but is still portable, by using
comments of the form `/*! ... */'.  In this case, MySQL Server will
parse and execute the code within the comment as it would any other
MySQL statement, but other SQL servers will ignore the extensions.  For
example:

     SELECT /*! STRAIGHT_JOIN */ col_name FROM table1,table2 WHERE ...

If you add a version number after the `!' character, the syntax within
the comment will be executed only if the MySQL version is equal to or
newer than the specified version number:

     CREATE /*!32302 TEMPORARY */ TABLE t (a INT);

This means that if you have Version 3.23.02 or newer, MySQL Server will
use the `TEMPORARY' keyword.

The following descriptions list MySQL extensions, organized by category.

Organization of data on disk
     MySQL Server maps each database to a directory under the MySQL
     data directory, and tables within a database to filenames in the
     database directory.  This has a few implications:

        * Database names and table names are case sensitive in MySQL
          Server on operating systems that have case-sensitive
          filenames (such as most Unix systems). *Note Name case
          sensitivity::.

        * You can use standard system commands to back up, rename,
          move, delete, and copy tables that are managed by the
          `MyISAM' or `ISAM' storage engines.  For example, to rename a
          `MyISAM' table, rename the `.MYD', `.MYI', and `.frm' files
          to which the table corresponds.

     Database, table, index, column, or alias names may begin with a
     digit (but may not consist solely of digits).

General language syntax
        * Strings may be enclosed by either `"' or `'', not just by `''.

        * Use of `\' as an escape character in strings.

        * In SQL statements, you can access tables from different
          databases with the DB_NAME.TBL_NAME syntax.  Some SQL servers
          provide the same functionality but call this `User space'.
          MySQL Server doesn't support tablespaces such as used in
          statements like this: `CREATE TABLE ralph.my_table...IN
          my_tablespace'.


SQL statement syntax
        * The `ANALYZE TABLE', `CHECK TABLE', `OPTIMIZE TABLE', and
          `REPAIR TABLE' statements.

        * The `CREATE DATABASE' and `DROP DATABASE' statements.  *Note
          `CREATE DATABASE': CREATE DATABASE.

        * The `DO' statement.

        * `EXPLAIN SELECT' to get a description of how tables are
          joined.

        * The `FLUSH' and `RESET' statements.

        * The `SET' statement. *Note `SET': SET OPTION.

        * The `SHOW' statement.  *Note `SHOW': SHOW.

        * Use of `LOAD DATA INFILE'. In many cases, this syntax is
          compatible with Oracle's `LOAD DATA INFILE'. *Note `LOAD
          DATA': LOAD DATA.

        * Use of `RENAME TABLE'. *Note `RENAME TABLE': RENAME TABLE.

        * Use of `REPLACE' instead of `DELETE' + `INSERT'.  *Note
          `REPLACE': REPLACE.

        * Use of `CHANGE col_name', `DROP col_name', or `DROP INDEX',
          `IGNORE' or `RENAME' in an `ALTER TABLE' statement.  Use of
          multiple `ADD', `ALTER', `DROP', or `CHANGE' clauses in an
          `ALTER TABLE' statement.  *Note `ALTER TABLE': ALTER TABLE.

        * Use of index names, indexes on a prefix of a field, and use of
          `INDEX' or `KEY' in a `CREATE TABLE' statement. *Note `CREATE
          TABLE': CREATE TABLE.

        * Use of `TEMPORARY' or `IF NOT EXISTS' with `CREATE TABLE'.

        * Use of `IF EXISTS' with `DROP TABLE'.

        * You can drop multiple tables with a single `DROP TABLE'
          statement.

        * The `ORDER BY' and `LIMIT' clauses of the `UPDATE' and
          `DELETE' statements.

        * `INSERT INTO ... SET col_name = ...' syntax.

        * The `DELAYED' clause of the `INSERT' and `REPLACE' statements.

        * The `LOW_PRIORITY' clause of the `INSERT', `REPLACE',
          `DELETE', and `UPDATE' statements.

        * Use of `INTO OUTFILE' and `STRAIGHT_JOIN' in a `SELECT'
          statement. *Note `SELECT': SELECT.

        * The `SQL_SMALL_RESULT' option in a `SELECT' statement.

        * You don't need to name all selected columns in the `GROUP BY'
          part.  This gives better performance for some very specific,
          but quite normal queries.  *Note Group by functions and
          modifiers::.

        * You can specify `ASC' and `DESC' with `GROUP BY'.

        * The ability to set variables in a statement with the `:='
          assignment operator:
               mysql> SELECT @a:=SUM(total),@b=COUNT(*),@a/@b AS avg
                   -> FROM test_table;
               mysql> SELECT @t1:=(@t2:=1)+@t3:=4,@t1,@t2,@t3;


Column types
        * The column types `MEDIUMINT', `SET', `ENUM', and the
          different `BLOB' and `TEXT' types.

        * The column attributes `AUTO_INCREMENT', `BINARY', `NULL',
          `UNSIGNED', and `ZEROFILL'.

Functions and operators
        * To make it easier for users who come from other SQL
          environments, MySQL Server supports aliases for many
          functions. For example, all string functions support both
          standard SQL syntax and ODBC syntax.

        * MySQL Server understands the `||' and `&&' operators to mean
          logical OR and AND, as in the C programming language.  In
          MySQL Server, `||' and `OR' are synonyms, as are `&&' and
          `AND'.  Because of this nice syntax, MySQL Server doesn't
          support the standard SQL `||' operator for string
          concatenation; use `CONCAT()' instead. Because `CONCAT()'
          takes any number of arguments, it's easy to convert use of
          the `||' operator to MySQL Server.

        * Use of `COUNT(DISTINCT list)' where `list' has more than one
          element.

        * All string comparisons are case-insensitive by default, with
          sort ordering determined by the current character set
          (ISO-8859-1 Latin1 by default).  If you don't like this, you
          should declare your columns with the `BINARY' attribute or
          use the `BINARY' cast, which causes comparisons to be done
          using the underlying character code values rather then a
          lexical ordering.

        * The `%' operator is a synonym for `MOD()'.  That is, `N % M'
          is equivalent to `MOD(N,M)'.  `%' is supported for C
          programmers and for compatibility with PostgreSQL.

        * The `=', `<>', `<=' ,`<', `>=',`>', `<<', `>>', `<=>', `AND',
          `OR', or `LIKE' operators may be used in column comparisons
          to the left of the `FROM' in `SELECT' statements.  For
          example:

               mysql> SELECT col1=1 AND col2=2 FROM TBL_NAME;

        * The `LAST_INSERT_ID()' function that returns the most recent
          `AUTO_INCREMENT' value.  *Note Information functions::.

        * `LIKE' is allowed on numeric columns.

        * The `REGEXP' and `NOT REGEXP' extended regular expression
          operators.

        * `CONCAT()' or `CHAR()' with one argument or more than two
          arguments.  (In MySQL Server, these functions can take any
          number of arguments.)

        * The `BIT_COUNT()', `CASE', `ELT()', `FROM_DAYS()',
          `FORMAT()', `IF()', `PASSWORD()', `ENCRYPT()', `MD5()',
          `ENCODE()', `DECODE()', `PERIOD_ADD()', `PERIOD_DIFF()',
          `TO_DAYS()', and `WEEKDAY()' functions.

        * Use of `TRIM()' to trim substrings.  Standard SQL supports
          removal of single characters only.

        * The `GROUP BY' functions `STD()', `BIT_OR()', `BIT_AND()',
          `BIT_XOR()', and `GROUP_CONCAT()'.  *Note Group by functions
          and modifiers::.

For a prioritized list indicating when new extensions will be added to
MySQL Server, you should consult the online MySQL TODO list at
`http://dev.mysql.com/doc/mysql/en/TODO.html'.  That is the latest
version of the TODO list in this manual. *Note TODO::.

MySQL Differences from Standard SQL
-----------------------------------

We try to make MySQL Server follow the ANSI SQL standard and the ODBC
SQL standard, but MySQL Server performs operations differently in some
cases:

   * For `VARCHAR' columns, trailing spaces are removed when the value
     is stored. *Note Bugs::.

   * In some cases, `CHAR' columns are silently converted to `VARCHAR'
     columns when you define a table or alter its structure.  *Note
     Silent column changes::.

   * Privileges for a table are not automatically revoked when you
     delete a table. You must explicitly issue a `REVOKE' statement to
     revoke privileges for a table. *Note `GRANT': GRANT.

Subqueries
..........

MySQL 4.1 supports subqueries and derived tables.  A "subquery" is a
`SELECT' statement nested within another statement.  A "derived table"
(an unnamed view) is a subquery in the `FROM' clause of another
statement.  *Note Subqueries::.

For MySQL versions older than 4.1, most subqueries can be rewritten
using joins or other methods.  See *Note Rewriting subqueries:: for
examples that show how to do this.

`SELECT INTO TABLE'
...................

MySQL Server doesn't support the Sybase SQL extension: `SELECT ... INTO
TABLE ...'.  Instead, MySQL Server supports the standard SQL syntax
`INSERT INTO ... SELECT ...', which is basically the same thing. *Note
`INSERT SELECT': INSERT SELECT.

     INSERT INTO tbl_temp2 (fld_id)
         SELECT tbl_temp1.fld_order_id
         FROM tbl_temp1 WHERE tbl_temp1.fld_order_id > 100;

Alternatively, you can use `SELECT INTO OUTFILE ...' or `CREATE TABLE
... SELECT'.

From version 5.0, MySQL supports `SELECT ... INTO' with user variables.
The same syntax may also be used inside stored procedures using cursors
and local variables.  *Note SELECT INTO Statement::.

Transactions and Atomic Operations
..................................

MySQL Server (version 3.23-max and all versions 4.0 and above) supports
transactions with the `InnoDB' and `BDB' transactional storage engines.
`InnoDB' provides _full_ `ACID' compliance.  *Note Storage engines::.

The other non-transactional storage engines in MySQL Server (such as
`MyISAM') follow a different paradigm for data integrity called "atomic
operations." In transactional terms, `MyISAM' tables effectively always
operate in `AUTOCOMMIT=1' mode.  Atomic operations often offer
comparable integrity with higher performance.

With MySQL Server supporting both paradigms, you can decide whether your
applications are best served by the speed of atomic operations or the
use of transactional features. This choice can be made on a per-table
basis.

As noted, the trade-off for transactional versus non-transactional table
types lies mostly in performance. Transactional tables have
significantly higher memory and diskspace requirements, and more CPU
overhead.  On the other hand, transactional table types such as
`InnoDB' also offer many significant features. MySQL Server's modular
design allows the concurrent use of different storage engines to suit
different requirements and deliver optimum performance in all
situations.

But how do you use the features of MySQL Server to maintain rigorous
integrity even with the non-transactional `MyISAM' tables, and how do
these features compare with the transactional table types?

  1. If your applications are written in a way that is dependent on
     being able to call `ROLLBACK' rather than `COMMIT' in critical
     situations, transactions are more convenient. Transactions also
     ensure that unfinished updates or corrupting activities are not
     committed to the database; the server is given the opportunity to
     do an automatic rollback and your database is saved.

     If you use non-transactional tables, MySQL Server in almost all
     cases allows you to resolve potential problems by including simple
     checks before updates and by running simple scripts that check the
     databases for inconsistencies and automatically repair or warn if
     such an inconsistency occurs. Note that just by using the MySQL
     log or even adding one extra log, you can normally fix tables
     perfectly with no data integrity loss.

  2. More often than not, critical transactional updates can be
     rewritten to be atomic. Generally speaking, all integrity problems
     that transactions solve can be done with `LOCK TABLES' or atomic
     updates, ensuring that you never will get an automatic abort from
     the server, which is a common problem with transactional database
     systems.

  3. Even a transactional system can lose data if the server goes down.
     The difference between different systems lies in just how small the
     time-lag is where they could lose data. No system is 100% secure,
     only "secure enough." Even Oracle, reputed to be the safest of
     transactional database systems, is reported to sometimes lose data
     in such situations.

     To be safe with MySQL Server, whether or not using transactional
     tables, you only need to have backups and have binary logging
     turned on. With this you can recover from any situation that you
     could with any other transactional database system.  It is always
     good to have backups, regardless of which database system you use.

The transactional paradigm has its benefits and its drawbacks. Many
users and application developers depend on the ease with which they can
code around problems where an abort appears to be, or is necessary.
However, even if you are new to the atomic operations paradigm, or more
familiar with transactions, do consider the speed benefit that
non-transactional tables can offer on the order of three to five times
the speed of the fastest and most optimally tuned transactional tables.

In situations where integrity is of highest importance, MySQL Server
offers transaction-level reliability and integrity even for
non-transactional tables.  If you lock tables with `LOCK TABLES', all
updates will stall until any integrity checks are made. If you obtain a
`READ LOCAL' lock (as opposed to a write lock) for a table that allows
concurrent inserts at the end of the table, reads are allowed, as are
inserts by other clients.  The new inserted records will not be seen by
the client that has the read lock until it releases the lock.  With
`INSERT DELAYED', you can queue inserts into a local queue, until the
locks are released, without having the client wait for the insert to
complete. *Note INSERT DELAYED::.

"Atomic," in the sense that we mean it, is nothing magical. It only
means that you can be sure that while each specific update is running,
no other user can interfere with it, and there will never be an
automatic rollback (which can happen with transactional tables if you
are not very careful).  MySQL Server also guarantees that there will
not be any dirty reads.

Following are some techniques for working with non-transactional tables:

   * Loops that need transactions normally can be coded with the help of
     `LOCK TABLES', and you don't need cursors to update records on the
     fly.

   * To avoid using `ROLLBACK', you can use the following strategy:

       1. Use `LOCK TABLES' to lock all the tables you want to access.

       2. Test the conditions that must be true before performing the
          update.

       3. Update if everything is okay.

       4. Use `UNLOCK TABLES' to release your locks.

     This is usually a much faster method than using transactions with
     possible rollbacks, although not always. The only situation this
     solution doesn't handle is when someone kills the threads in the
     middle of an update. In this case, all locks will be released but
     some of the updates may not have been executed.

   * You can also use functions to update records in a single operation.
     You can get a very efficient application by using the following
     techniques:

        * Modify columns relative to their current value.

        * Update only those columns that actually have changed.

     For example, when we are doing updates to some customer
     information, we update only the customer data that has changed and
     test only that none of the changed data, or data that depends on
     the changed data, has changed compared to the original row. The
     test for changed data is done with the `WHERE' clause in the
     `UPDATE' statement. If the record wasn't updated, we give the
     client a message: "Some of the data you have changed has been
     changed by another user." Then we show the old row versus the new
     row in a window so that the user can decide which version of the
     customer record to use.

     This gives us something that is similar to column locking but is
     actually even better because we only update some of the columns,
     using values that are relative to their current values.  This
     means that typical `UPDATE' statements look something like these:

          UPDATE tablename SET pay_back=pay_back+125;

          UPDATE customer
            SET
              customer_date='current_date',
              address='new address',
              phone='new phone',
              money_owed_to_us=money_owed_to_us-125
            WHERE
              customer_id=id AND address='old address' AND phone='old phone';

     This is very efficient and works even if another client has
     changed the values in the `pay_back' or `money_owed_to_us' columns.

   * In many cases, users have wanted `LOCK TABLES' and/or `ROLLBACK'
     for the purpose of managing unique identifiers.  This can be
     handled much more efficiently without locking or rolling back by
     using an `AUTO_INCREMENT' column and either the `LAST_INSERT_ID()'
     SQL function or the `mysql_insert_id()' C API function.  *Note
     Information functions::.  *Note `mysql_insert_id()':
     mysql_insert_id.

     You can generally code around the need for row-level locking. Some
     situations really do need it, and `InnoDB' tables support
     row-level locking. With `MyISAM' tables, you can use a flag column
     in the table and do something like the following:

          UPDATE TBL_NAME SET row_flag=1 WHERE id=ID;

     MySQL returns 1 for the number of affected rows if the row was
     found and `row_flag' wasn't already 1 in the original row.

     You can think of it as though MySQL Server changed the preceding
     query to:

          UPDATE TBL_NAME SET row_flag=1 WHERE id=ID AND row_flag <> 1;

Stored Procedures and Triggers
..............................

Stored procedures are implemented in MySQL version 5.0.  *Note Stored
Procedures::.

Triggers are currently being implemented, with basic functionality in
MySQL 5.0, with further development planned for MySQL 5.1.

Foreign Keys
............

In MySQL Server 3.23.44 and up, the `InnoDB' storage engine supports
checking of foreign key constraints, including `CASCADE', `ON DELETE',
and `ON UPDATE'. *Note InnoDB foreign key constraints::.

For storage engines other than `InnoDB', MySQL Server parses the
`FOREIGN KEY' syntax in `CREATE TABLE' statements, but does not use or
store it. In the future, the implementation will be extended to store
this information in the table specification file so that it may be
retrieved by `mysqldump' and ODBC.  At a later stage, foreign key
constraints will be implemented for `MyISAM' tables as well.

Foreign key enforcement offers several benefits to database developers:

   * Assuming proper design of the relationships, foreign key
     constraints make it more difficult for a programmer to introduce
     an inconsistency into the database.

   * Centralized checking of constraints by the database server makes it
     unnecessary to perform these checks on the application side. This
     eliminates the possibility that different applications may not all
     check the constraints in the same way.

   * Using cascading updates and deletes can simplify the application
     code.

   * Properly designed foreign key rules aid in documenting
     relationships between tables.

Do keep in mind that these benefits come at the cost of additional
overhead for the database server to perform the necessary checks.
Additional checking by the server affects performance, which for some
applications may be sufficiently undesirable as to be avoided if
possible.  (Some major commercial applications have coded the
foreign-key logic at the application level for this reason.)

MySQL gives database developers the choice of which approach to use. If
you don't need foreign keys and want to avoid the overhead associated
with enforcing referential integrity, you can choose another table type
instead, such as `MyISAM'. (For example, the `MyISAM' storage engine
offers very fast performance for applications that perform only
`INSERT' and `SELECT' operations, because the inserts can be performed
concurrently with retrievals.  *Note Table locking::.)

If you choose not to take advantage of referential integrity checks,
keep the following considerations in mind:

   * In the absence of server-side foreign key relationship checking,
     the application itself must handle relationship issues.  For
     example, it must take care to insert rows into tables in the proper
     order, and to avoid creating orphaned child records. It must also
     be able to recover from errors that occur in the middle of
     multiple-record insert operations.

   * If `ON DELETE' is the only referential integrity capability an
     application needs, note that as of MySQL Server 4.0, you can use
     multiple-table `DELETE' statements to delete rows from many tables
     with a single statement. *Note `DELETE': DELETE.

   * A workaround for the lack of `ON DELETE' is to add the appropriate
     `DELETE' statement to your application when you delete records
     from a table that has a foreign key. In practice, this is often as
     quick as using foreign keys, and is more portable.


Be aware that the use of foreign keys can in some instances lead to
problems:

   * Foreign key support addresses many referential integrity issues,
     but it is still necessary to design key relationships carefully to
     avoid circular rules or incorrect combinations of cascading
     deletes.

   * It is not uncommon for a DBA to create a topology of relationships
     that makes it difficult to restore individual tables from a backup.
     (MySQL alleviates this difficulty by allowing you to temporarily
     disable foreign key checks when reloading a table that depends on
     other tables.  *Note InnoDB foreign key constraints::.  As of
     MySQL 4.1.1, `mysqldump' generates dump files that take advantage
     of this capability automatically when reloaded.)

Note that foreign keys in SQL are used to check and enforce referential
integrity, not to join tables.  If you want to get results from multiple
tables from a `SELECT' statement, you do this by performing a join
between them:

     SELECT * FROM t1, t2 WHERE t1.id = t2.id;

*Note `JOIN': JOIN. *Note example-Foreign keys::.

The `FOREIGN KEY' syntax without `ON DELETE ...' is often used by ODBC
applications to produce automatic `WHERE' clauses.

Views
.....

Views (updatable) are being implemented in the 5.0 version of MySQL
Server.  They are already available in binary releases from 5.0.1 and
up.  *Note CREATE VIEW::.

Views are useful for allowing users to access a set of relations
(tables) as if it were a single table, and limiting their access to
just that.  Views can also be used to restrict access to rows (a subset
of a particular table).  For access control to columns, you can also
use the sophisticated privilege system in MySQL Server.  *Note
Privilege system::.

In designing an implementation of views, our ambitious goal, as much as
is possible within the confines of SQL, has been full compliance with
"Codd's Rule #6" for relational database systems: "All views that are
theoretically updatable, should in practice also be updatable."

`--' as the Start of a Comment
..............................

Some other SQL databases use `--' to start comments.  MySQL Server uses
`#' as the start comment character. You can also use the C comment
style `/* this is a comment */' with MySQL Server.  *Note Comments::.

MySQL Server 3.23.3 and above support the `--' comment style, provided
the comment is followed by a space (or by a control character such as a
newline). The requirement for a space is to prevent problems with
automatically generated SQL queries that have used something like the
following code, where we automatically insert the value of the payment
for `!payment!':

     UPDATE account SET credit=credit-!payment!

Think about what happens if the value of `payment' is a negative value
such as `-1':

     UPDATE account SET credit=credit--1

`credit--1' is a legal expression in SQL, but if `--' is interpreted as
the start of a comment, part of the expression is discarded. The result
is a statement that has a completely different meaning than intended:

     UPDATE account SET credit=credit

The statement produces no change in value at all!  This illustrates that
allowing comments to start with `--' can have serious consequences.

Using our implementation of this method of commenting in MySQL Server
3.23.3 and up, `credit--1' is actually safe.

Another safe feature is that the `mysql' command-line client removes
all lines that start with `--'.

The following information is relevant only if you are running a MySQL
version earlier than 3.23.3:

If you have an SQL program in a text file that contains `--' comments,
you should use the `replace' utility as follows to convert the comments
to use `#' characters:

     shell> replace " --" " #" < text-file-with-funny-comments.sql \
              | mysql DB_NAME

instead of the usual:

     shell> mysql DB_NAME < text-file-with-funny-comments.sql

You can also edit the command file "in place" to change the `--'
comments to `#' comments:

     shell> replace " --" " #" -- text-file-with-funny-comments.sql

Change them back with this command:

     shell> replace " #" " --" -- text-file-with-funny-comments.sql

How MySQL Deals with Constraints
--------------------------------

MySQL allows you to work both with transactional tables that allow
rollback and with non-transactional tables that do not. Because of this,
constraint handling is a bit different in MySQL than in other databases.
We must handle the case when you have inserted or updated a lot of rows
in a non-transactional table for which changes cannot be rolled back
when an error occurs.

The basic philosophy is that MySQL Server tries to produce an error for
anything that it can detect while parsing a statement to be executed,
and tries to recover from any errors that occur while executing the
statement.  We do this in most cases, but not yet for all. *Note TODO
future::.

The options MySQL has when an error occurs are to stop the statement in
the middle or to recover as well as possible from the problem and
continue.  By default, the server follows the latter course. This
means, for example, that the server may coerce illegal values to the
closest legal values.

Beginning with MySQL 5.0.2, several SQL mode options are available to
provide greater control over how accepting to be of bad data values and
whether to continue executing a statement or abort it when errors
occur. Using these options, you can configure MySQL Server to act in a
more traditional fashion that is like other DBMSs that reject improper
input. The SQL mode can be set at runtime, which enables individual
clients to select the behavior most appropriate for their requirements.
*Note Server SQL mode::.

The following sections describe what happens for the different types of
constraints.

`PRIMARY KEY' and `UNIQUE' Index Constraints
............................................

Normally, an error occurs when you try to `INSERT' or `UPDATE' a row
that causes a primary key, unique key, or foreign key violation.  If
you are using a transactional storage engine such as `InnoDB', MySQL
automatically rolls back the statement.  If you are using a
non-transactional storage engine, MySQL stops processing the statement
at the row for which the error occurred and leaves any remaining rows
unprocessed.

If you wish to ignore such key violations, MySQL supports an `IGNORE'
keyword for `INSERT' and `UPDATE'. In this case, MySQL ignores any key
violations and continues processing with the next row.  *Note `INSERT':
INSERT.  *Note `UPDATE': UPDATE.

You can get information about the number of rows actually inserted or
updated with the `mysql_info()' C API function.  *Note `mysql_info()':
mysql_info.  In MySQL 4.1 and up, you also can use the `SHOW WARNINGS'
statement.  *Note `SHOW WARNINGS': SHOW WARNINGS.

For the moment, only `InnoDB' tables support foreign keys.  *Note
InnoDB foreign key constraints::.  Foreign key support in `MyISAM'
tables is scheduled for implementation in MySQL 5.1.

Constraints on Invalid Data
...........................

Before MySQL 5.0.2, MySQL is forgiving of illegal or improper data
values and coerces them to legal values for data entry. In MySQL 5.0.2
and up, that remains the default behavior, but you can select more
traditional treatment of bad values such that the server rejects them
and aborts the the statement in which they occur.  This section
describes the default (forgiving) behavior of MySQL, as well as the
newer strict SQL mode and how it differs.

The following holds true when you are not using strict mode.  If you
insert an "incorrect" value into a column, such as a `NULL' into a `NOT
NULL' column or a too-large numeric value into a numeric column, MySQL
sets the column to the "best possible value" instead of producing an
error:

   * If you try to store an out of range value in a numeric column,
     MySQL Server instead stores zero, the smallest possible value, or
     the largest possible value in the column.

   * For strings, MySQL stores either the empty string or the longest
     possible string that can be in the column.

   * If you try to store a string that doesn't start with a number into
     a numeric column, MySQL Server stores 0.

   * If you try to store `NULL' into a column that doesn't take `NULL'
     values, MySQL Server stores 0 or `''' (the empty string) instead.

   * MySQL allows you to store certain incorrect date values into
     `DATE' and `DATETIME' columns (such as `'2000-02-31'' or
     `'2000-02-00'').  The idea is that it's not the job of the SQL
     server to validate dates. If MySQL can store a date value and
     retrieve exactly the same value, MySQL stores it as given.  If the
     date is totally wrong (outside the server's ability to store it),
     the special date value `'0000-00-00'' is stored in the column
     instead.

   * If an `INSERT' statement specifies no value for a column, MySQL
     inserts its default value if the column definition includes an
     explicit `DEFAULT' clause. If the definition has no such `DEFAULT'
     clause, MySQL inserts the implicit default value for the column
     data type.  In general, this is the empty string for string
     columns, 0 for numeric columns, and `'0000-00-00'' for date
     columns.  Implicit default values are discussed in *Note `CREATE
     TABLE': CREATE TABLE.


The reason for the preceding rules is that we can't check these
conditions until the statement has begun executing.  We can't just roll
back if we encounter a problem after updating a few rows, because the
storage engine may not support rollback.  The option of terminating the
statement is not that good; in this case, the update would be "half
done," which is probably the worst possible scenario.  In this case,
it's better to "do the best you can" and then continue as if nothing
happened.

In MySQL 5.0.2 and up, you can select stricter treatment of input
values by using the `STRICT_TRANS_TABLES' or `STRICT_ALL_TABLES' SQL
modes.  *Note Server SQL mode::.

`STRICT_TRANS_TABLES' works like this: For transactional storage
engines, bad data values occurring anywhere in the statement causes the
to abort and roll back.  For non-transactional storage engines, the
statement aborts if the error occurs in the first row to be inserted or
updated.  (In this case, the statement can be regarded to leave the
table unchanged, just as for a transactional table.)  Errors in rows
after the first do not abort the statement. Instead, bad data values
are adjusted and result in warnings rather than errors.  In other words,
with `STRICT_TRANS_TABLES', a wrong value causes MySQL to roll back, if
it can, all updates done so far.

For stricter checking, enable `STRICT_ALL_TABLES'. This is the same as
`STRICT_TRANS_TABLES' except that for non-transactional storage engines,
errors abort the statement even for bad data in rows following the
first row.  This means that if an error occurs partway through a
multiple-row insert or update for a non-transactional table, a partial
update results.  Earlier rows are inserted or updated, but those from
the point of the error on are not.  To avoid this for non-transactional
tables, either use single-row statements or else use
`STRICT_TRANS_TABLES' if conversion warnings rather than errors are
acceptable.  To avoid problems in the first place, do not use MySQL to
check column content. It is safest (and often faster) to let the
application ensure that it passes only legal values to the database.

With either of the strict mode options, you can cause errors to be
treated as warnings by using `INSERT IGNORE' or `UPDATE IGNORE'.

`ENUM' and `SET' Constraints
............................

`ENUM' and `SET' columns provide an efficient way to define columns
that can contain only a given set of values.  However, before MySQL
5.0.2, `ENUM' and `SET' are not real constraints.  This is for the same
reasons that `NOT NULL' is not honored.  *Note constraint invalid
data::.

`ENUM' columns always have a default value. If you don't specify a
default value, then it will be `NULL' for columns that can have `NULL',
otherwise the first enumeration value is used as the default value.

If you insert an incorrect value into an `ENUM' column or if you force
a value into an `ENUM' column with `IGNORE', it is set to the reserved
enumeration value of `0', which is displayed as an empty string in
string context. *Note `ENUM': ENUM.

If you insert an incorrect value into a `SET' column, the incorrect
value is ignored. For example, if the column can contain the values
`'a'', `'b'', and `'c'', an attempt to assign `'a,x,b,y'' results in a
value of `'a,b''.  *Note `SET': SET.

As of MySQL 5.0.2, you can configure the server to use strict SQL mode.
*Note Server SQL mode::.  When strict mode is not enabled, values
entered into `ENUM' and `SET' columns are handled as just described for
MySQL 4.x.  However, if strict mode is enabled, the definition of a
`ENUM' or `SET' column does act as a constraint on values entered into
the column. An error occurs for values that do not satisify these
conditions:

   * An `ENUM' value must be one of those listed in the column
     definition, or the internal numeric equivalent thereof. The value
     cannot be the error value (that is, 0 or the empty string).  For a
     column defined as `ENUM('a','b','c')', values such as `''', `'d'',
     and `'ax'' are illegal and are rejected.

   * A `SET' value must be the empty string or a value consisting of
     one or more of the values listed in the column definition
     separated by commas.  For a column defined as `SET('a','b','c')',
     values such as `'d'', and `'a,b,c,d'' are illegal and are rejected.


Errors for invalid values can be suppressed in strict mode if you use
`INSERT IGNORE' or `UPDATE IGNORE'.  In this case, a warning is
generated rather than an error. For `ENUM', the value is inserted as the
error member (`0'). For `SET', the value is inserted as given except
that that any invalid substrings are deleted. For example, `'a,x,b,y''
results in a value of `'a,b'', as described earlier.

Known Errors and Design Deficiencies in MySQL
---------------------------------------------

Errors in 3.23 Fixed in a Later MySQL Version
.............................................

The following known errors or bugs are not fixed in MySQL 3.23 because
fixing them would involve changing a lot of code that could introduce
other even worse bugs. The bugs are also classified as "not fatal" or
"bearable."

   * You should avoid using spaces at the end of column names because
     this can cause weird behavior. (Fixed in MySQL 4.0.) (Bug #4196)

   * You can get a deadlock (hung thread) if you use `LOCK TABLE' to
     lock multiple tables and then in the same connection use `DROP
     TABLE' to drop one of them while another thread is trying to lock
     it.  (To break the deadlock, you can use `KILL' to terminate any
     of the threads involved.)  This issue is resolved as of MySQL
     4.0.12.

   * `SELECT MAX(key_column) FROM t1,t2,t3...' where one of the tables
     are empty doesn't return `NULL' but instead returns the maximum
     value for the column.  This issue is resolved as of MySQL 4.0.11.

   * `DELETE FROM heap_table' without a `WHERE' clause doesn't work on
     a locked `HEAP' table.

Errors in 4.0 Fixed in a Later MySQL Version
............................................

The following known errors or bugs are not fixed in MySQL 4.0 because
fixing them would involve changing a lot of code that could introduce
other even worse bugs. The bugs are also classified as "not fatal" or
"bearable."

   * In a `UNION', the first `SELECT' determines the type,
     `max_length', and `NULL' properties for the resulting columns.
     This issue is resolved as of MySQL 4.1.1; the property values are
     based on the rows from all `UNION' parts.

   * In `DELETE' with many tables, you can't refer to tables to be
     deleted through an alias. This is fixed as of MySQL 4.1.

   * You cannot mix `UNION ALL' and `UNION DISTINCT' in the same query.
     If you use `ALL' for one `UNION', it is used for all of them.
     This is fixed as of MySQL 4.1.2. The rules for mixed `UNION' types
     are given in *Note `UNION': UNION.

   * `FLUSH TABLES WITH READ LOCK' does not block `CREATE TABLE', which
     may cause a problem with the binary log position when doing a full
     backup of tables and the binary log.

Open Bugs and Design Deficiencies in MySQL
..........................................

The following problems are known and fixing them is a high priority:

   * Even if you are using `lower_case_table_names=2' (which enables
     MySQL to remember the used case for databases and table names)
     MySQL will not on case insensitive systems remember the used case
     for database names for the function `DATABASE()' or in various
     logs.

   * Dropping a `FOREIGN KEY' constraint doesn't work in replication
     because the constraint may have another name on the slave.

   * `REPLACE' (and `LOAD DATA' with the `REPLACE' option) does not
     trigger `ON DELETE CASCADE'.

   * `DISTINCT' with `ORDER BY' doesn't work inside `GROUP_CONCAT()' if
     you don't use all and only those columns that are in the
     `DISTINCT' list.

   * If one user has a long-running transaction and another user drops a
     table that is updated in the transaction, there is small chance
     that the binary log may contain the `DROP TABLE' command before
     the table is used in the transaction itself.  We plan to fix this
     in 5.0 by having the `DROP TABLE' wait until the table is not used
     in any transaction.

   * When inserting a big integer value (between 2^63 and 2^64-1) into a
     decimal/string column, it is inserted as a negative value because
     the number is evaluated in a signed integer context. We plan to
     fix this in MySQL 4.1.

     `FLUSH TABLES WITH READ LOCK' does not block `COMMIT' if the server
     is running without binary logging, which may cause a problem (of
     consistency between tables) when doing a full backup.

   * `ANALYZE TABLE' on a `BDB' table may in some cases make the table
     unusable until you restart `mysqld'.  If this happens, you will
     see errors of the following form in the MySQL error file:

          001207 22:07:56  bdb:  log_flush: LSN past current end-of-log

   * MySQL accepts parentheses in the `FROM' clause of a `SELECT'
     statement, but silently ignores them.  The reason for not giving
     an error is that many clients that automatically generate queries
     add parentheses in the `FROM' clause even where they are not
     needed.

   * Concatenating many `RIGHT JOINS' or combining `LEFT' and `RIGHT'
     join in the same query may not give a correct answer because MySQL
     only generates `NULL' rows for the table preceding a `LEFT' or
     before a `RIGHT' join.  This will be fixed in 5.0 at the same time
     we add support for parentheses in the `FROM' clause.

   * Don't execute `ALTER TABLE' on a `BDB' table on which you are
     running multiple-statement transactions until all those
     transactions complete.  (The transaction will probably be ignored.)

   * `ANALYZE TABLE', `OPTIMIZE TABLE', and `REPAIR TABLE' may cause
     problems on tables for which you are using `INSERT DELAYED'.

   * Doing a `LOCK TABLE ...' and `FLUSH TABLES ...' doesn't guarantee
     that there isn't a half-finished transaction in progress on the
     table.

   * `BDB' tables are a bit slow to open. If you have many `BDB' tables
     in a database, it will take a long time to use the `mysql' client
     on the database if you are not using the `-A' option or if you are
     using `rehash'. This is especially notable when you have a large
     table cache.

   * Replication uses query-level logging: The master writes the
     executed queries to the binary log. This is a very fast, compact,
     and efficient logging method that works perfectly in most cases.
     Although we have never heard of it actually occurring, it is
     theoretically possible for the data on the master and slave to
     become different if a query is designed in such a way that the
     data modification is non-deterministic; that is, left to the will
     of the query optimizer. (That generally is not a good practice
     anyway, even outside of replication!)  For example:

        - `CREATE ... SELECT' or `INSERT ... SELECT'  statements that
          insert zero or `NULL' values into an `AUTO_INCREMENT' column.

        - `DELETE' if you are deleting rows from a table that has
          foreign keys with `ON DELETE CASCADE' properties.

        - `REPLACE ... SELECT', `INSERT IGNORE ... SELECT' if you have
          duplicate key values in the inserted data.
     *If and only if all these queries have no `ORDER BY' clause
     guaranteeing a deterministic order*.

     For example, for `INSERT ... SELECT' with no `ORDER BY', the
     `SELECT' may return rows in a different order (which will result
     in a row having different ranks, hence getting a different number
     in the `AUTO_INCREMENT' column), depending on the choices made by
     the optimizers on the master and slave. A query will be optimized
     differently on the master and slave only if:

        - The files used by the two queries are not exactly the same;
          for example, `OPTIMIZE TABLE' was run on the master tables
          and not on the slave tables. (To fix this, `OPTIMIZE TABLE',
          `ANALYZE TABLE', and `REPAIR TABLE' are written to the binary
          log as of MySQL 4.1.1).

        - The table is stored using a different storage engine on the
          master than on the slave. (It is possible to use different
          storage engines on the master and slave. For example, you can
          use `InnoDB' on the master, but `MyISAM' on the slave if the
          slave has less available disk space.)

        - MySQL buffer sizes (`key_buffer_size', and so on) are
          different on the master and slave.

        - The master and slave run different MySQL versions, and the
          optimizer code differs between these versions.

     This problem may also affect database restoration using
     `mysqlbinlog|mysql'.

     The easiest way to avoid this problem in all cases is to add an
     `ORDER BY' clause to such non-deterministic queries to ensure that
     the rows are always stored or modified in the same order.  In
     future MySQL versions, we will automatically add an `ORDER BY'
     clause when needed.


The following problems are known and will be fixed in due time:

   * Log filenames are based on the server hostname (if you don't
     specify a filename with the startup option). For now you have to
     use options like `--log-bin=OLD_HOST_NAME-bin' if you change your
     hostname to something else. Another option is to just rename the
     old files to reflect your hostname change. *Note Server options::.

   * `mysqlbinlog' will not delete temporary files left after a `LOAD
     DATA INFILE' command. *Note `mysqlbinlog': mysqlbinlog.

   * `RENAME' doesn't work with `TEMPORARY' tables or tables used in a
     `MERGE' table.

   * When using the `RPAD()' function in a query that has to be
     resolved by using a temporary table, all resulting strings will
     have rightmost spaces removed. This is an example of such a query:

          SELECT RPAD(t1.column1, 50, ' ') AS f2, RPAD(t2.column2, 50, ' ') AS f1
          FROM table1 as t1 LEFT JOIN table2 AS t2 ON t1.record=t2.joinID
          ORDER BY t2.record;

     The final result of this bug is that you will not be able to get
     spaces on the right side of the resulting values. The problem also
     occurs for any other string function that adds spaces to the right.

     The reason for this is due to the fact that `HEAP' tables, which
     are used first for temporary tables, are not capable of handling
     `VARCHAR' columns.

     This behavior exists in all versions of MySQL.  It will be fixed
     in one of the 4.1 series releases.

   * Due to the way table definition files are stored, you cannot use
     character 255 (`CHAR(255)') in table names, column names, or
     enumerations.  This is scheduled to be fixed in version 5.1 when
     we have new table definition format files.

   * When using `SET CHARACTER SET', you can't use translated
     characters in database, table, and column names.

   * You can't use `_' or `%' with `ESCAPE' in `LIKE ... ESCAPE'.

   * If you have a `DECIMAL' column in which the same number is stored
     in different formats (for example, `+01.00', `1.00', `01.00'),
     `GROUP BY' may regard each value as a different value.

   * You cannot build the server in another directory when using
     MIT-pthreads. Because this requires changes to MIT-pthreads, we
     are not likely to fix this. *Note MIT-pthreads::.

   * `BLOB' and `TEXT'values can't "reliably" be used in `GROUP BY' or
     `ORDER BY' or `DISTINCT'. Only the first `max_sort_length' bytes
     are used when comparing `BLOB' values in these cases.  The default
     value of `max_sort_length' value is 1024. It can be changed at
     server startup time.  As of MySQL 4.0.3, it can also be changed at
     runtime. For older versions, a workaround for most cases is to use
     a substring.  For example:

          SELECT DISTINCT LEFT(BLOB_COL,2048) FROM TBL_NAME;

   * Numeric calculations are done with `BIGINT' or `DOUBLE' (both are
     normally 64 bits long). Which precision you get depends on the
     function.  The general rule is that bit functions are done with
     `BIGINT' precision, `IF' and `ELT()' with `BIGINT' or `DOUBLE'
     precision, and the rest with `DOUBLE' precision.  You should try to
     avoid using unsigned long long values if they resolve to be bigger
     than 63 bits (9223372036854775807) for anything other than bit
     fields.  MySQL Server 4.0 has better `BIGINT' handling than 3.23.

   * All string columns, except `BLOB' and `TEXT' columns, automatically
     have all trailing spaces removed when retrieved. For `CHAR' types,
     this is okay. The bug is that in MySQL Server, `VARCHAR' columns
     are treated the same way.

   * You can have only up to 255 `ENUM' and `SET' columns in one table.

   * In `MIN()', `MAX()', and other aggregate functions, MySQL
     currently compares `ENUM' and `SET' columns by their string value
     rather than by the string's relative position in the set.

   * `mysqld_safe' redirects all messages from `mysqld' to the `mysqld'
     log.  One problem with this is that if you execute `mysqladmin
     refresh' to close and reopen the log, `stdout' and `stderr' are
     still redirected to the old log.  If you use `--log' extensively,
     you should edit `mysqld_safe' to log to `HOST_NAME.err' instead of
     `HOST_NAME.log' so that you can easily reclaim the space for the
     old log by deleting the old one and executing `mysqladmin refresh'.

   * In the `UPDATE' statement, columns are updated from left to right.
     If you refer to an updated column, you get the updated value
     instead of the original value. For example, the following
     statement increments `KEY' by `2', not `1':

          mysql> UPDATE TBL_NAME SET KEY=KEY+1,KEY=KEY+1;

   * You can refer to multiple temporary tables in the same query, but
     you cannot refer to any given temporary table more than once.  For
     example, the following doesn't work:

          mysql> SELECT * FROM temp_table, temp_table AS t2;
          ERROR 1137: Can't reopen table: 'temp_table'

   * The optimizer may handle `DISTINCT' differently when you are using
     "hidden" columns in a join than when you are not.  In a join,
     hidden columns are counted as part of the result (even if they are
     not shown), whereas in normal queries, hidden columns don't
     participate in the `DISTINCT' comparison.  We will probably change
     this in the future to never compare the hidden columns when
     executing `DISTINCT'.

     An example of this is:

          SELECT DISTINCT mp3id FROM band_downloads
                 WHERE userid = 9 ORDER BY id DESC;

     and

          SELECT DISTINCT band_downloads.mp3id
                 FROM band_downloads,band_mp3
                 WHERE band_downloads.userid = 9
                 AND band_mp3.id = band_downloads.mp3id
                 ORDER BY band_downloads.id DESC;

     In the second case, you might in MySQL Server 3.23.x get two
     identical rows in the result set (because the values in the hidden
     `id' column may differ).

     Note that this happens only for queries where you don't have the
     `ORDER BY' columns in the result.

   * Because MySQL Server allows you to work with table types that don't
     support transactions, and thus can't roll back data, some things
     behave a little differently in MySQL Server than in other SQL
     servers.  This is just to ensure that MySQL Server never needs to
     do a rollback for an SQL statement.  This may be a little awkward
     at times because column values must be checked in the application,
     but this will actually give you a nice speed increase because it
     allows MySQL Server to do some optimizations that otherwise would
     be very hard to do.

     If you set a column to an incorrect value, MySQL Server will,
     instead of doing a rollback, store the "best possible value" in
     the column. For information about how this occurs, see *Note
     Constraints::.

   * If you execute a `PROCEDURE' on a query that returns an empty set,
     in some cases the `PROCEDURE' will not transform the columns.

   * Creation of a table of type `MERGE' doesn't check whether the
     underlying tables are of compatible types.

   * If you use `ALTER TABLE' first to add a `UNIQUE' index to a table
     used in a `MERGE' table and then to add a normal index on the
     `MERGE' table, the key order will be different for the tables if
     there was an old key that was not unique in the table. This is
     because `ALTER TABLE' puts `UNIQUE' indexes before normal indexes
     to be able to detect duplicate keys as early as possible.

The following are known bugs in earlier versions of MySQL:

   * In the following case you can get a core dump:

        - Delayed insert handler has pending inserts to a table.

        - `LOCK TABLE' with `WRITE'.

        - `FLUSH TABLES'.

   * Before MySQL Server 3.23.2, an `UPDATE' that updated a key with a
     `WHERE' on the same key may have failed because the key was used to
     search for records and the same row may have been found multiple
     times:

          UPDATE TBL_NAME SET KEY=KEY+1 WHERE KEY > 100;

     A workaround is to use:

          UPDATE TBL_NAME SET KEY=KEY+1 WHERE KEY+0 > 100;

     This will work because MySQL Server will not use an index on
     expressions in the `WHERE' clause.

   * Before MySQL Server 3.23, all numeric types were treated as
     fixed-point fields. That means that you had to specify how many
     decimals a floating-point field should have. All results were
     returned with the correct number of decimals.

For information about platform-specific bugs, see the installation and
porting instructions in *Note Operating System Specific Notes:: and
*Note Porting::.

Installing MySQL
****************

This chapter describes how to obtain and install MySQL:

  1. *Determine whether your platform is supported.*  Please note that
     not all supported systems are equally good for running MySQL on
     them.  On some it is much more robust and efficient than others.
     See *Note Which OS:: for details.

  2. *Choose which distribution to install.*  Several versions of MySQL
     are available, and most are available in several distribution
     formats.  You can choose from pre-packaged distributions
     containing binary (precompiled) programs or source code.  When in
     doubt, use a binary distribution.  We also provide public access
     to our current source tree for those who want to see our most
     recent developments and help us test new code.  To determine which
     version and type of distribution you should use, see *Note Which
     version::.

  3. *Download the distribution that you want to install.* For a list
     of sites from which you can obtain MySQL, see *Note Getting MySQL:
     Getting MySQL.  You can verify the integrity of the distribution
     using the instructions in *Note Verifying Package Integrity::.

  4. *Install the distribution.*  To install MySQL from a binary
     distribution, use the instructions in *Note Quick Standard
     Installation::.  To install MySQL from a source distribution or
     from the current development source tree, use the instructions in
     *Note Installing source::.

     *Note*: If you plan to upgrade an existing version of MySQL to a
     newer version rather than installing MySQL for the first time, see
     *Note Upgrade:: for information about upgrade procedures and about
     issues that you should consider before upgrading.

     If you encounter installation difficulties, see *Note Operating
     System Specific Notes:: for information on solving problems for
     particular platforms.

  5. *Perform any necessary post-installation setup.* After installing
     MySQL, read *Note Post-installation::.  This section contains
     important information about making sure the MySQL server is
     working properly. It also describes how to secure the initial
     MySQL user accounts, _which have no passwords_ until you assign
     passwords.  The section applies whether you install MySQL using a
     binary or source distribution.

  6. If you want to run the MySQL benchmark scripts, Perl support for
     MySQL must be available.  *Note Perl support::.


General Installation Issues
===========================

Before installing MySQL, you should do the following:

  1. Determine whether or not MySQL runs on your platform.

  2. Choose a distribution to install.

  3. Download the distribution and verify its integrity.


This section contains the information necessary to carry out these
steps.  After doing so, you can use the instructions in later sections
of the chapter to install the distribution that you choose.

Operating Systems Supported by MySQL
------------------------------------

This section lists the operating systems on which you can expect to be
able to run MySQL.

We use GNU Autoconf, so it is possible to port MySQL to all modern
systems that have a C++ compiler and a working implementation of POSIX
threads.  (Thread support is needed for the server. To compile only the
client code, the only requirement is a C++ compiler.) We use and
develop the software ourselves primarily on Linux (SuSE and Red Hat),
FreeBSD, and Sun Solaris (Versions 8 and 9).

MySQL has been reported to compile successfully on the following
combinations of operating system and thread package.  Note that for many
operating systems, native thread support works only in the latest
versions.

   * AIX 4.x, 5.x with native threads.  *Note IBM-AIX::.

   * Amiga.

   * BSDI 2.x with the MIT-pthreads package.  *Note BSDI::.

   * BSDI 3.0, 3.1 and 4.x with native threads.  *Note BSDI::.

   * Digital Unix 4.x with native threads.  *Note Alpha-DEC-UNIX::.

   * FreeBSD 2.x with the MIT-pthreads package.  *Note FreeBSD::.

   * FreeBSD 3.x and 4.x with native threads.  *Note FreeBSD::.

   * FreeBSD 4.x with LinuxThreads.  *Note FreeBSD::.

   * HP-UX 10.20 with the DCE threads or the MIT-pthreads package.
     *Note HP-UX 10.20::.

   * HP-UX 11.x with the native threads.  *Note HP-UX 11.x::.

   * Linux 2.0+ with LinuxThreads 0.7.1+ or `glibc' 2.0.7+ for various
     CPU architectures.  *Note Linux::.

   * Mac OS X.  *Note Mac OS X::.

   * NetBSD 1.3/1.4 Intel and NetBSD 1.3 Alpha (requires GNU make).
     *Note NetBSD::.

   * Novell NetWare 6.0.  *Note NetWare installation::.

   * OpenBSD > 2.5 with native threads. OpenBSD < 2.5 with the
     MIT-pthreads package.  *Note OpenBSD::.

   * OS/2 Warp 3, FixPack 29 and OS/2 Warp 4, FixPack 4.  *Note OS/2::.

   * SCO OpenServer with a recent port of the FSU Pthreads package.
     *Note SCO::.

   * SCO UnixWare 7.1.x.  *Note SCO UnixWare::.

   * SGI Irix 6.x with native threads.  *Note SGI-Irix::.

   * Solaris 2.5 and above with native threads on SPARC and x86.  *Note
     Solaris::.

   * SunOS 4.x with the MIT-pthreads package.  *Note Solaris::.

   * Tru64 Unix.  *Note Alpha-DEC-UNIX::.

   * Windows 9x, Me, NT, 2000, and XP.  *Note Windows installation::.

Not all platforms are equally well-suited for running MySQL. How well a
certain platform is suited for a high-load mission-critical MySQL
server is determined by the following factors:

   * General stability of the thread library. A platform may have an
     excellent reputation otherwise, but MySQL will be only as stable
     as the thread library if that library is unstable in the code that
     is called by MySQL, even if everything else is perfect.

   * The capability of the kernel and the thread library to take
     advantage of symmetric multi-processor (SMP) systems. In other
     words, when a process creates a thread, it should be possible for
     that thread to run on a different CPU than the original process.

   * The capability of the kernel and the thread library to run many
     threads that acquire and release a mutex over a short critical
     region frequently without excessive context switches. If the
     implementation of `pthread_mutex_lock()' is too anxious to yield
     CPU time, this will hurt MySQL tremendously. If this issue is not
     taken care of, adding extra CPUs will actually make MySQL slower.

   * General filesystem stability and performance.

   * If your tables are big, the ability of the filesystem to deal with
     large files at all and to deal with them efficiently.

   * Our level of expertise here at MySQL AB with the platform. If we
     know a platform well, we enable platform-specific optimizations
     and fixes at compile time. We can also provide advice on
     configuring your system optimally for MySQL.

   * The amount of testing we have done internally for similar
     configurations.

   * The number of users that have successfully run MySQL on the
     platform in similar configurations. If this number is high, the
     chances of encountering platform-specific surprises are much
     smaller.

Based on the preceding criteria, the best platforms for running MySQL
at this point are x86 with SuSE Linux using a 2.4 kernel, and ReiserFS
(or any similar Linux distribution) and SPARC with Solaris (2.7-9).
FreeBSD comes third, but we really hope it will join the top club once
the thread library is improved. We also hope that at some point we will
be able to include into the top category all other platforms on which
MySQL currently compiles and runs okay, but not quite with the same
level of stability and performance.  This will require some effort on
our part in cooperation with the developers of the operating system and
library components that MySQL depends on. If you are interested in
improving one of those components, are in a position to influence its
development, and need more detailed instructions on what MySQL needs to
run better, send an email message to the MySQL `internals' mailing list.
*Note Mailing-list::.

Please note that the purpose of the preceding comparison is not to say
that one operating system is better or worse than another in general.
We are talking only about choosing an OS for the specific purpose of
running MySQL.  With this in mind, the result of this comparison would
be different if we considered more factors. In some cases, the reason
one OS is better than the other could simply be that we have been able
to put more effort into testing and optimizing for a particular
platform.  We are just stating our observations to help you decide
which platform to use for running MySQL.

Choosing Which MySQL Distribution to Install
--------------------------------------------

When preparing to install MySQL, you should decide which version to
use.  MySQL development occurs in several release series, and you can
pick the one that best fits your needs.  After deciding which version
to install, you can choose a distribution format.  Releases are
available in binary or source format.

Choosing Which Version of MySQL to Install
..........................................

The first decision to make is whether you want to use a production
(stable) release or a development release.  In the MySQL development
process, multiple release series co-exist, each at a different stage of
maturity:

   * MySQL 5.0 is the newest development release series and is under
     very active development for new features. Alpha releases have been
     issued to allow more widespread testing.

   * MySQL 4.1 is in gamma status, soon moving to production status.

   * MySQL 4.0 is the current stable (production-quality) release
     series.  New releases are issued for bugfixes. No new features are
     added that could diminish the code stability.

   * MySQL 3.23 is the old stable (production-quality) release series.
     This series is retired, so new releases are issued only to fix
     critical bugs.


We don't believe in a complete freeze, as this also leaves out bugfixes
and things that "must be done."  "Somewhat frozen" means that we may add
small things that "almost surely will not affect anything that's already
working." Naturally, relevant bugfixes from an earlier series propagate
to later series.

Normally, if you are beginning to use MySQL for the first time or trying
to port it to some system for which there is no binary distribution, we
recommend going with the production release series. Currently this is
MySQL 4.0.  All MySQL releases, even those from development series, are
checked with the MySQL benchmarks and an extensive test suite before
being issued.

If you are running an old system and want to upgrade, but don't want to
take the chance of having a non-seamless upgrade, you should upgrade to
the latest version in the same release series you are using (where only
the last part of the version number is newer than yours).  We have tried
to fix only fatal bugs and make small, relatively safe changes to that
version.

If you want to use new features not present in the production release
series, you can use a version from a development series. Note that
development releases are not as stable as production releases.

If you want to use the very latest sources containing all current
patches and bugfixes, you can use one of our BitKeeper repositories.
These are not "releases" as such, but are available as previews of the
code on which future releases will be based.

The MySQL naming scheme uses release names that consist of three
numbers and a suffix; for example, `mysql-4.1.2-alpha'.  The numbers
within the release name are interpreted like this:

   * The first number (`4') is the major version and also describes the
     file format.  All Version 4 releases have the same file format.

   * The second number (`1') is the release level.  Taken together, the
     major version and release level constitute the release series
     number.

   * The third number (`2') is the version number within the release
     series.  This is incremented for each new release.  Usually you
     want the latest version for the series you have chosen.


For each minor update, the last number in the version string is
incremented.  When there are major new features or minor
incompatibilities with previous versions, the second number in the
version string is incremented.  When the file format changes, the first
number is increased.

Release names also include a suffix to indicates the stability level of
the release.  Releases within a series progress through a set of
suffixes to indicate how the stability level improves.  The possible
suffixes are:

   * `alpha' indicates that the release contains some large section of
     new code that hasn't been 100% tested.  Known bugs (usually there
     are none) should be documented in the News section.  *Note News::.
     There are also new commands and extensions in most alpha
     releases.  Active development that may involve major code changes
     can occur in an alpha release, but everything will be tested
     before issuing a release.  For this reason, there should be no
     known bugs in any MySQL release.

   * `beta' means that all new code has been tested.  No major new
     features that could cause corruption in old code are added.  There
     should be no known bugs.  A version changes from alpha to beta
     when there haven't been any reported fatal bugs within an alpha
     version for at least a month and we have no plans to add any
     features that could make any old command unreliable.

   * `gamma' is a beta that has been around a while and seems to work
     fine.  Only minor fixes are added.  This is what many other
     companies call a release.

   * If there is no suffix, it means that the version has been run for a
     while at many different sites with no reports of bugs other than
     platform-specific bugs.  Only critical bugfixes are applied to the
     release. This is what we call a production (stable) release.

MySQL uses a naming scheme that is slightly different from most other
products.  In general, it's relatively safe to use any version that has
been out for a couple of weeks without being replaced with a new
version within the release series.

All releases of MySQL are run through our standard tests and benchmarks
to ensure that they are relatively safe to use.  Because the standard
tests are extended over time to check for all previously found bugs,
the test suite keeps getting better.

All releases have been tested at least with:

An internal test suite
     The `mysql-test' directory contains an extensive set of test cases.
     We run these tests for virtually every server binary.  See *Note
     MySQL test suite:: for more information about this test suite.

The MySQL benchmark suite
     This suite runs a range of common queries.  It is also a test to
     see whether the latest batch of optimizations actually made the
     code faster.  *Note MySQL Benchmarks::.

The `crash-me' test
     This test tries to determine what features the database supports
     and what its capabilities and limitations are.  *Note MySQL
     Benchmarks::.

Another test is that we use the newest MySQL version in our internal
production environment, on at least one machine.  We have more than
100GB of data to work with.

Choosing a Distribution Format
..............................

After choosing which version of MySQL to install, you should decide
whether to use a binary distribution or a source distribution.  In most
cases, you should probably use a binary distribution, if one exists for
your platform. Binary distributions are available in native format for
many platforms, such as RPM files for Linux or DMG package installers
for Mac OS X. Distributions also are available as Zip archives or
compressed `tar' files.

Reasons to choose a binary distribution include the following:

   * Binary distributions generally are easier to install than source
     distributions.

   * To satisfy different user requirements, we provide two different
     binary versions: one compiled with the non-transactional storage
     engines (a small, fast binary), and one configured with the most
     important extended options like transaction-safe tables.  Both
     versions are compiled from the same source distribution.  All
     native MySQL clients can connect to servers from either MySQL
     version.

     The extended MySQL binary distribution is marked with the `-max'
     suffix and is configured with the same options as `mysqld-max'.
     *Note `mysqld-max': mysqld-max.

     If you want to use the `MySQL-Max' RPM, you must first install the
     standard `MySQL-server' RPM.


Under some circumstances, you probably will be better off installing
MySQL from a source distribution:

   * You want to install MySQL at some explicit location.  The standard
     binary distributions are "ready to run" at any place, but you may
     want to have even more flexibility to place MySQL components where
     you want.

   * You want to configure `mysqld' with some extra features that are
     not included in the standard binary distributions.  Here is a list
     of the most common extra options that you may want to use:

        * `--with-innodb' (default for MySQL 4.0 and up)

        * `--with-berkeley-db' (not available on all platforms)

        * `--with-raid'

        * `--with-libwrap'

        * `--with-named-z-libs' (this is done for some of the binaries)

        * `--with-debug[=FULL]'

   * You want to configure `mysqld' without some features that are
     included in the standard binary distributions. For example,
     distributions normally are compiled with support for all character
     sets. If you want a smaller MySQL server, you can recompile it
     with support for only the character sets you need.

   * You have a special compiler (such as `pgcc') or want to use
     compiler options that are better optimized for your processor.
     Binary distributions are compiled with options that should work on
     a variety of processors from the same processor family.

   * You want to use the latest sources from one of the BitKeeper
     repositories to have access to all current bugfixes. For example,
     if you have found a bug and reported it to the MySQL development
     team, the bugfix will be committed to the source repository and you
     can access it there.  The bugfix will not appear in a release until
     a release actually is issued.

   * You want to read (or modify) the C and C++ code that makes up
     MySQL. For this purpose, you should get a source distribution,
     because the source code is always the ultimate manual.

   * Source distributions contain more tests and examples than binary
     distributions.


How and When Updates Are Released
.................................

MySQL is evolving quite rapidly here at MySQL AB and we want to share
new developments with other MySQL users.  We try to make a release when
we have very useful features that others seem to have a need for.

We also try to help out users who request features that are easy to
implement.  We take note of what our licensed users want to have, and
we especially take note of what our extended email-supported customers
want and try to help them out.

No one has to download a new release.  The News section will tell you if
the new release has something you really want.  *Note News::.

We use the following policy when updating MySQL:

   * Releases are issued within each series. For each release, the last
     number in the version is one more than the previous release within
     the same series.

   * Production (stable) releases are meant to appear about 1-2 times a
     year.  However, if small bugs are found, a release with only
     bugfixes will be issued.

   * Working releases/bugfixes to old releases are meant to appear about
     every 4-8 weeks.

   * Binary distributions for some platforms are made by us for major
     releases.  Other people may make binary distributions for other
     systems, but probably less frequently.

   * We make fixes available as soon as we have identified and corrected
     small or non-critical but annoying bugs. The fixes are available
     immediately from our public BitKeeper repositories, and will be
     included in the next release.

   * If by any chance a fatal bug is found in a release, we will make a
     new release as soon as possible.  (We would like other companies
     to do this, too!)

Release Philosophy--No Known Bugs in Releases
.............................................

We put a lot of time and effort into making our releases bug-free.  To
our knowledge, we have not released a single MySQL version with any
_known_ "fatal" repeatable bugs.  (A "fatal" bug is something that
crashes MySQL under normal usage, produces incorrect answers for normal
queries, or has a security problem.)

We have documented all open problems, bugs, and issues that are
dependent on design decisions.  *Note Bugs::.

Our aim is to fix everything that is fixable without risk of making a
stable MySQL version less stable. In certain cases, this means we can
fix an issue in the development versions, but not in the stable
(production) version. Naturally, we document such issues so that users
are aware of them.

Here is a description of how our build process works:
   * We monitor bugs from our customer support list, the bugs database
     at `http://bugs.mysql.com/', and the MySQL external mailing lists.

   * All reported bugs for live versions are entered into the bugs
     database.

   * When we fix a bug, we always try to make a test case for it and
     include it into our test system to ensure that the bug will never
     recur without being detected. (About 90% of all fixed bugs have a
     test case.)

   * We create test cases for all new features we add to MySQL.

   * Before we start to build a new MySQL release, we ensure that all
     reported repeatable bugs for the MySQL version (3.23.x, 4.0.x, etc)
     are fixed.  If something is impossible to fix (due to some internal
     design decision in MySQL), we document this in the manual.  *Note
     Bugs::.

   * We do a build on all platforms for which we support binaries (15+
     platforms) and run our test suite and benchmark suite on all of
     them.

   * We will not publish a binary for a platform for which the test or
     benchmark suite fails.  If the problem is due to a general error
     in the source, we fix it and do the build plus tests on all
     systems again from scratch.

   * The build and test process takes 2-3 days.  If we receive a report
     regarding a fatal bug during this process (for example, one that
     causes a core dump), we fix the problem and restart the build
     process.

   * After publishing the binaries on `http://dev.mysql.com/', we send
     out an announcement message to the `mysql' and `announce' mailing
     lists.  *Note Mailing-list::.  The announcement message contains a
     list of all changes to the release and any known problems with the
     release.  The Known Problems section in the release notes has been
     needed for only a handful of releases.

   * To quickly give our users access to the latest MySQL features, we
     do a new MySQL release every 4-8 weeks.  Source code snapshots are
     built daily and are available at
     `http://downloads.mysql.com/snapshots.php'.

   * If, despite our best efforts, we get any bug reports after the
     release is done that there was something critically wrong with the
     build on a specific platform, we will fix it at once and build a
     new `'a'' release for that platform. Thanks to our large user
     base, problems are found quickly.

   * Our track record for making good releases is quite good.  In the
     last 150 releases, we had to do a new build for fewer than 10
     releases. In three of these cases, the bug was a faulty `glibc'
     library on one of our build machines that took us a long time to
     track down.

MySQL Binaries Compiled by MySQL AB
...................................

As a service of MySQL AB, we provide a set of binary distributions of
MySQL that are compiled on systems at our site or on systems where
supporters of MySQL kindly have given us access to their machines.

In addition to the binaries provided in platform-specific package
formats, we offer binary distributions for a number of platforms in the
form of compressed `tar' files (`.tar.gz' files).  *Note Quick Standard
Installation::.

For Windows distributions, see *Note Windows installation::.

These distributions are generated using the script
`Build-tools/Do-compile', which compiles the source code and creates
the binary `tar.gz' archive using `scripts/make_binary_distribution'.

These binaries are configured and built with the following compilers and
options. This information can also be obtained by looking at the
variables `COMP_ENV_INFO' and `CONFIGURE_LINE' inside the script
`bin/mysqlbug' of every binary `tar' file distribution.

The following binaries are built on MySQL AB development systems:

Linux 2.4.xx x86 with `gcc' 2.95.3:
     `CFLAGS="-O2 -mcpu=pentiumpro" CXX=gcc CXXFLAGS="-O2
     -mcpu=pentiumpro -felide-constructors" ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --enable-assembler --disable-shared
     --with-client-ldflags=-all-static
     --with-mysqld-ldflags=-all-static'

Linux 2.4.x x86 with `icc' (Intel C++ Compiler 8.0):
     `CC=icc CXX=icc CFLAGS="-O3 -unroll2 -ip -mp -no-gcc -restrict"
     CXXFLAGS="-O3 -unroll2 -ip -mp -no-gcc -restrict" ./configure
     --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --enable-assembler --disable-shared
     --with-client-ldflags=-all-static
     --with-mysqld-ldflags=-all-static --with-embedded-server
     --with-innodb'

Linux 2.4.xx Intel Itanium 2 with `ecc' (Intel C++ Itanium Compiler 7.0):
     `CC=ecc CFLAGS="-O2 -tpp2 -ip -nolib_inline" CXX=ecc CXXFLAGS="-O2
     -tpp2 -ip -nolib_inline" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile'

Linux 2.4.xx Intel Itanium with `ecc' (Intel C++ Itanium Compiler 7.0):
     `CC=ecc CFLAGS=-tpp1 CXX=ecc CXXFLAGS=-tpp1 ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile'

Linux 2.4.xx alpha with `ccc' (Compaq C V6.2-505 / Compaq C++ V6.3-006):
     `CC=ccc CFLAGS="-fast -arch generic" CXX=cxx CXXFLAGS="-fast -arch
     generic -noexceptions -nortti" ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --with-mysqld-ldflags=-non_shared
     --with-client-ldflags=-non_shared --disable-shared'

Linux 2.x.xx ppc with `gcc' 2.95.4:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --disable-shared --with-embedded-server --with-innodb'

Linux 2.4.xx s390 with `gcc' 2.95.3:
     `CFLAGS="-O2" CXX=gcc CXXFLAGS="-O2 -felide-constructors"
     ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --disable-shared
     --with-client-ldflags=-all-static
     --with-mysqld-ldflags=-all-static'

Linux 2.4.xx x86_64 (AMD64) with `gcc' 3.2.1:
     `CXX=gcc ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile  --disable-shared'

Sun Solaris 8 x86 with `gcc' 3.2.3:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --disable-shared --with-innodb'

Sun Solaris 8 SPARC with `gcc' 3.2:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --enable-assembler --with-named-z-libs=no
     --with-named-curses-libs=-lcurses --disable-shared'

Sun Solaris 8 SPARC 64-bit with `gcc' 3.2:
     `CC=gcc CFLAGS="-O3 -m64 -fno-omit-frame-pointer" CXX=gcc
     CXXFLAGS="-O3 -m64 -fno-omit-frame-pointer -felide-constructors
     -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --with-named-z-libs=no
     --with-named-curses-libs=-lcurses --disable-shared'

Sun Solaris 9 SPARC with `gcc' 2.95.3:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --enable-assembler
     --with-named-curses-libs=-lcurses --disable-shared'

Sun Solaris 9 SPARC with `cc-5.0' (Sun Forte 5.0):
     `CC=cc-5.0 CXX=CC ASFLAGS="-xarch=v9" CFLAGS="-Xa -xstrconst -mt
     -D_FORTEC_ -xarch=v9" CXXFLAGS="-noex -mt -D_FORTEC_ -xarch=v9"
     ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --enable-assembler --with-named-z-libs=no
     --enable-thread-safe-client --disable-shared'

IBM AIX 4.3.2 ppc with `gcc' 3.2.3:
     `CFLAGS="-O2 -mcpu=powerpc -Wa,-many " CXX=gcc CXXFLAGS="-O2
     -mcpu=powerpc -Wa,-many  -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --with-named-z-libs=no --disable-shared'

IBM AIX 4.3.3 ppc with `xlC_r' (IBM Visual Age C/C++ 6.0):
     `CC=xlc_r CFLAGS="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192"
     CXX=xlC_r CXXFLAGS ="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192"
     ./configure --prefix=/usr/local/mysql
     --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --with-named-z-libs=no --disable-shared --with-innodb'

IBM AIX 5.1.0 ppc with `gcc' 3.3:
     `CFLAGS="-O2 -mcpu=powerpc -Wa,-many" CXX=gcc CXXFLAGS="-O2
     -mcpu=powerpc -Wa,-many  -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --with-named-z-libs=no --disable-shared'

IBM AIX 5.2.0 ppc with `xlC_r' (IBM Visual Age C/C++ 6.0):
     `CC=xlc_r CFLAGS="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192"
     CXX=xlC_r CXXFLAGS="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192"
     ./configure --prefix=/usr/local/mysql
     --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --with-named-z-libs=no --disable-shared --with-embedded-server
     --with-innodb'

HP-UX 10.20 pa-risc1.1 with `gcc' 3.1:
     `CFLAGS="-DHPUX -I/opt/dce/include -O3 -fPIC" CXX=gcc
     CXXFLAGS="-DHPUX -I/opt/dce /include -felide-constructors
     -fno-exceptions -fno-rtti -O3 -fPIC" ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile  --with-pthread
     --with-named-thread-libs=-ldce --with-lib-ccflags=-fPIC
     --disable-shared'

HP-UX 11.00 pa-risc with `aCC' (HP ANSI C++ B3910B A.03.50):
     `CC=cc CXX=aCC CFLAGS=+DAportable CXXFLAGS=+DAportable ./configure
     --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile --disable-shared
     --with-embedded-server --with-innodb'

HP-UX 11.11 pa-risc2.0 64bit with `aCC' (HP ANSI C++ B3910B A.03.33):
     `CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile --disable-shared'

HP-UX 11.11 pa-risc2.0 32bit with `aCC' (HP ANSI C++ B3910B A.03.33):
     `CC=cc CXX=aCC CFLAGS="+DAportable" CXXFLAGS="+DAportable"
     ./configure --prefix=/usr/local/mysql
     --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --disable-shared --with-innodb'

HP-UX 11.22 ia64 64bit with `aCC' (HP aC++/ANSI C B3910B A.05.50):
     `CC=cc CXX=aCC CFLAGS="+DD64 +DSitanium2" CXXFLAGS="+DD64
     +DSitanium2" ./configure --prefix=/usr/local/mysql
     --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --disable-shared --with-embedded-server --with-innodb'

Apple Mac OS X 10.2 powerpc with `gcc' 3.1:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile  --disable-shared'

FreeBSD 4.7 i386 with `gcc' 2.95.4:
     `CFLAGS=-DHAVE_BROKEN_REALPATH ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --enable-assembler --with-named-z-libs=not-used --disable-shared'

FreeBSD 4.7 i386 using LinuxThreads with `gcc' 2.95.4:
     `CFLAGS="-DHAVE_BROKEN_REALPATH -D__USE_UNIX98 -D_REENTRANT
     -D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads"
     CXXFLAGS="-DHAVE_BROKEN_REALPATH -D__USE_UNIX98 -D_REENTRANT
     -D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads"
     ./configure --prefix=/usr/local/mysql
     --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --enable-thread-safe-client
     --enable-local-infile --enable-assembler
     --with-named-thread-libs="-DHAVE_GLIBC2_STYLE_GETHOSTBYNAME_R
     -D_THREAD_SAFE -I /usr/local/include/pthread/linuxthreads
     -L/usr/local/lib -llthread -llgcc_r" --disable-shared
     --with-embedded-server --with-innodb'

QNX Neutrino 6.2.1 i386 with `gcc' 2.95.3qnx-nto 20010315:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile  --disable-shared'

The following binaries are built on third-party systems kindly provided
to MySQL AB by other users. These are provided only as a courtesy;
MySQL AB does not have full control over these systems, so we can
provide only limited support for the binaries built on them.

SCO Unix 3.2v5.0.6 i386 with `gcc' 2.95.3:
     `CFLAGS="-O3 -mpentium" LDFLAGS=-static CXX=gcc CXXFLAGS="-O3
     -mpentium -felide-constructors" ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --with-named-z-libs=no --enable-thread-safe-client
     --disable-shared'

SCO OpenUnix 8.0.0 i386 with `CC' 3.2:
     `CC=cc CFLAGS="-O" CXX=CC ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --with-named-z-libs=no
     --enable-thread-safe-client --disable-shared'

Compaq Tru64 OSF/1 V5.1 732 alpha with `cc/cxx' (Compaq C V6.3-029i / DIGITAL C++ V6.1-027):
     `CC="cc -pthread" CFLAGS="-O4 -ansi_alias -ansi_args -fast -inline
     speed -speculate all" CXX="cxx -pthread" CXXFLAGS="-O4 -ansi_alias
     -fast -inline speed -speculate all -noexceptions -nortti"
     ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --with-prefix=/usr/local/mysql
     --with-named-thread-libs="-lpthread -lmach -lexc -lc"
     --disable-shared --with-mysqld-ldflags=-all-static'

SGI Irix 6.5 IP32 with `gcc' 3.0.1:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile  --disable-shared'

FreeBSD/sparc64 5.0 with `gcc' 3.2.1:
     `CFLAGS=-DHAVE_BROKEN_REALPATH ./configure
     --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile --disable-shared
     --with-innodb'

The following compile options have been used for binary packages that
MySQL AB provided in the past. These binaries no longer are being
updated, but the compile options are listed here for reference purposes.

Linux 2.2.xx SPARC with `egcs' 1.1.2:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --enable-assembler --disable-shared'

Linux 2.2.x with x686 with `gcc' 2.95.2:
     `CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro
     -felide-constructors -fno-exceptions -fno-rtti" ./configure
     --prefix=/usr/local/mysql --enable-assembler
     --with-mysqld-ldflags=-all-static --disable-shared
     --with-extra-charsets=complex'

SunOS 4.1.4 2 sun4c with `gcc' 2.7.2.1:
     `CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors" ./configure
     --prefix=/usr/local/mysql --disable-shared
     --with-extra-charsets=complex --enable-assembler'

SunOS 5.5.1 (and above) sun4u with `egcs' 1.0.3a or 2.90.27 or
     `gcc' 2.95.2 and newer: `CC=gcc CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3
     -felide-constructors -fno-exceptions -fno-rtti" ./configure
     --prefix=/usr/local/mysql --with-low-memory
     --with-extra-charsets=complex --enable-assembler'

SunOS 5.6 i86pc with `gcc' 2.8.1:
     `CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql
     --with-low-memory --with-extra-charsets=complex'

BSDI BSD/OS 3.1 i386 with `gcc' 2.7.2.1:
     `CC=gcc CXX=gcc CXXFLAGS=-O ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex'

BSDI BSD/OS 2.1 i386 with `gcc' 2.7.2:
     `CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex'

AIX 4.2 with `gcc' 2.7.2.2:
     `CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex'

Anyone who has more optimal options for any of the preceding
configurations listed can always mail them to the MySQL `internals'
mailing list.  *Note Mailing-list::.

RPM distributions prior to MySQL 3.22 are user-contributed.  Beginning
with MySQL 3.22, RPM distributions are generated by MySQL AB.

If you want to compile a debug version of MySQL, you should add
`--with-debug' or `--with-debug=full' to the preceding `configure'
commands and remove any `-fomit-frame-pointer' options.

How to Get MySQL
----------------

Check the MySQL downloads page (`http://dev.mysql.com/downloads/') for
information about the current version and for downloading instructions.
For a complete up-to-date list of MySQL download mirror sites, see
`http://dev.mysql.com/downloads/mirrors.html'.  There you will also
find information about becoming a MySQL mirror site and how to report a
bad or out-of-date mirror.

Our main mirror is located at `http://mirrors.sunsite.dk/mysql/'.

Verifying Package Integrity Using MD5 Checksums or `GnuPG'
----------------------------------------------------------

After you have downloaded the MySQL package that suits your needs and
before you attempt to install it, you should make sure that it is
intact and has not been tampered with. MySQL AB offers three means of
integrity checking:

   * MD5 checksums

   * Cryptographic signatures using `GnuPG', the GNU Privacy Guard

   * For RPM packages, the built-in RPM integrity verification mechanism


The following sections describe how to use these methods.

If you notice that the MD5 checksum or GPG signatures do not match,
first try to download the respective package one more time, perhaps
from another mirror site. If you repeatedly cannot successfully verify
the integrity of the package, please notify us about such incidents,
including the full package name and the download site you have been
using, at <[e-mail]> or <[e-mail]>.  Do not report
downloading problems using the bug-reporting system.

Verifying the MD5 Checksum
..........................

After you have downloaded a MySQL package, you should make sure that
its MD5 checksum matches the one provided on the MySQL download pages.
Each package has an individual checksum that you can verify with the
following command, where `package_name' is the name of the package you
downloaded:

     shell> md5sum package_name

Example:
     shell> md5sum mysql-standard-4.0.17-pc-linux-i686.tar.gz
     60f5fe969d61c8f82e4f7f62657e1f06  mysql-standard-4.0.17-pc-linux-i686.tar.gz

You should verify that the resulting checksum (the string of hexadecimal
digits) matches the one displayed on the download page immediately
below the respective package.

Note that not all operating systems support the `md5sum' command. On
some, it is simply called `md5' and others do not ship it at all. On
Linux, it is part of the `GNU Text Utilities' package, which is
available for a wide range of platforms. You can download the source
code from `http://www.gnu.org/software/textutils/' as well. If you have
`OpenSSL' installed, you can also use the command `openssl md5
package_name' instead. A DOS/Windows implementation of the `md5'
command is available from `http://www.fourmilab.ch/md5/'.

Signature Checking Using `GnuPG'
................................

Another method of verifying the integrity and authenticity of a package
is to use cryptographic signatures. This is more reliable than using MD5
checksums, but requires more work.

Beginning with MySQL 4.0.10 (February 2003), MySQL AB started signing
downloadable packages with `GnuPG' (`GNU Privacy Guard').  `GnuPG' is
an Open Source alternative to the very well-known `Pretty Good Privacy'
(`PGP') by Phil Zimmermann.  See `http://www.gnupg.org/' for more
information about `GnuPG' and how to obtain and install it on your
system. Most Linux distributions already ship with `GnuPG' installed by
default.  For more information about `OpenPGP', see
`http://www.openpgp.org/'.

To verify the signature for a specific package, you first need to
obtain a copy of MySQL AB's public GPG build key. You can download the
key from `http://www.keyserver.net/'.  The key that you want to obtain
is named `[e-mail]'.  Alternatively, you can cut and paste the
key directly from the following text:

     Key ID:
     pub  1024D/5072E1F5 2003-02-03
          MySQL Package signing key (www.mysql.com) <[e-mail]>
     Fingerprint: A4A9 4068 76FC BD3C 4567  70C8 8C71 8D3B 5072 E1F5

     Public Key (ASCII-armored):

     -----BEGIN PGP PUBLIC KEY BLOCK-----
     Version: GnuPG v1.0.6 (GNU/Linux)
     Comment: For info see http://www.gnupg.org

     mQGiBD4+owwRBAC14GIfUfCyEDSIePvEW3SAFUdJBtoQHH/nJKZyQT7h9bPlUWC3
     RODjQReyCITRrdwyrKUGku2FmeVGwn2u2WmDMNABLnpprWPkBdCk96+OmSLN9brZ
     fw2vOUgCmYv2hW0hyDHuvYlQA/BThQoADgj8AW6/0Lo7V1W9/8VuHP0gQwCgvzV3
     BqOxRznNCRCRxAuAuVztHRcEAJooQK1+iSiunZMYD1WufeXfshc57S/+yeJkegNW
     hxwR9pRWVArNYJdDRT+rf2RUe3vpquKNQU/hnEIUHJRQqYHo8gTxvxXNQc7fJYLV
     K2HtkrPbP72vwsEKMYhhr0eKCbtLGfls9krjJ6sBgACyP/Vb7hiPwxh6rDZ7ITnE
     kYpXBACmWpP8NJTkamEnPCia2ZoOHODANwpUkP43I7jsDmgtobZX9qnrAXw+uNDI
     QJEXM6FSbi0LLtZciNlYsafwAPEOMDKpMqAK6IyisNtPvaLd8lH0bPAnWqcyefep
     rv0sxxqUEMcM3o7wwgfN83POkDasDbs3pjwPhxvhz6//62zQJ7Q7TXlTUUwgUGFj
     a2FnZSBzaWduaW5nIGtleSAod3d3Lm15c3FsLmNvbSkgPGJ1aWxkQG15c3FsLmNv
     bT6IXQQTEQIAHQUCPj6jDAUJCWYBgAULBwoDBAMVAwIDFgIBAheAAAoJEIxxjTtQ
     cuH1cY4AnilUwTXn8MatQOiG0a/bPxrvK/gCAJ4oinSNZRYTnblChwFaazt7PF3q
     zIhMBBMRAgAMBQI+PqPRBYMJZgC7AAoJEElQ4SqycpHyJOEAn1mxHijft00bKXvu
     cSo/pECUmppiAJ41M9MRVj5VcdH/KN/KjRtW6tHFPYhMBBMRAgAMBQI+QoIDBYMJ
     YiKJAAoJELb1zU3GuiQ/lpEAoIhpp6BozKI8p6eaabzF5MlJH58pAKCu/ROofK8J
     Eg2aLos+5zEYrB/LsrkCDQQ+PqMdEAgA7+GJfxbMdY4wslPnjH9rF4N2qfWsEN/l
     xaZoJYc3a6M02WCnHl6ahT2/tBK2w1QI4YFteR47gCvtgb6O1JHffOo2HfLmRDRi
     Rjd1DTCHqeyX7CHhcghj/dNRlW2Z0l5QFEcmV9U0Vhp3aFfWC4Ujfs3LU+hkAWzE
     7zaD5cH9J7yv/6xuZVw411x0h4UqsTcWMu0iM1BzELqX1DY7LwoPEb/O9Rkbf4fm
     Le11EzIaCa4PqARXQZc4dhSinMt6K3X4BrRsKTfozBu74F47D8Ilbf5vSYHbuE5p
     /1oIDznkg/p8kW+3FxuWrycciqFTcNz215yyX39LXFnlLzKUb/F5GwADBQf+Lwqq
     a8CGrRfsOAJxim63CHfty5mUc5rUSnTslGYEIOCR1BeQauyPZbPDsDD9MZ1ZaSaf
     anFvwFG6Llx9xkU7tzq+vKLoWkm4u5xf3vn55VjnSd1aQ9eQnUcXiL4cnBGoTbOW
     I39EcyzgslzBdC++MPjcQTcA7p6JUVsP6oAB3FQWg54tuUo0Ec8bsM8b3Ev42Lmu
     QT5NdKHGwHsXTPtl0klk4bQk4OajHsiy1BMahpT27jWjJlMiJc+IWJ0mghkKHt92
     6s/ymfdf5HkdQ1cyvsz5tryVI3Fx78XeSYfQvuuwqp2H139pXGEkg0n6KdUOetdZ
     Whe70YGNPw1yjWJT1IhMBBgRAgAMBQI+PqMdBQkJZgGAAAoJEIxxjTtQcuH17p4A
     n3r1QpVC9yhnW2cSAjq+kr72GX0eAJ4295kl6NxYEuFApmr1+0uUq/SlsQ==
     =YJkx
     -----END PGP PUBLIC KEY BLOCK-----

You can import the build key into your personal public GPG keyring by
using `gpg --import'. For example, if you save the key in a file named
`mysql_pubkey.asc', the import command looks like this:

     shell> gpg --import mysql_pubkey.asc

See the GPG documentation for more information on how to work with
public keys.

After you have downloaded and imported the public build key, download
your desired MySQL package and the corresponding signature, which also
is available from the download page.  The signature file has the same
name as the distribution file with an `.asc' extension. For example:

Distribution file      `mysql-standard-4.0.17-pc-linux-i686.tar.gz'
Signature file         `mysql-standard-4.0.17-pc-linux-i686.tar.gz.asc'

Make sure that both files are stored in the same directory and then run
the following command to verify the signature for the distribution file:

     shell> gpg --verify package_name.asc

Example:

     shell> gpg --verify mysql-standard-4.0.17-pc-linux-i686.tar.gz.asc
     gpg: Warning: using insecure memory!
     gpg: Signature made Mon 03 Feb 2003 08:50:39 PM MET
     using DSA key ID 5072E1F5
     gpg: Good signature from
          "MySQL Package signing key (www.mysql.com) <[e-mail]>"

The `Good signature' message indicates that everything is all right.
You can ignore the `insecure memory' warning.

Signature Checking Using `RPM'
..............................

For RPM packages, there is no separate signature. RPM packages have a
built-in GPG signature and MD5 checksum. You can verify a package by
running the following command:

     shell> rpm --checksig package_name.rpm

Example:

     shell> rpm --checksig MySQL-server-4.0.10-0.i386.rpm
     MySQL-server-4.0.10-0.i386.rpm: md5 gpg OK

*Note*: If you are using RPM 4.1 and it complains about `(GPG) NOT OK
(MISSING KEYS: GPG#5072e1f5)', even though you have imported the MySQL
public build key into your own GPG keyring, you need to import the key
into the RPM keyring first. RPM 4.1 no longer uses your personal GPG
keyring (or GPG itself). Rather, it maintains its own keyring because
it is a system-wide application and a user's GPG public keyring is a
user-specific file. To import the MySQL public key into the RPM
keyring, first obtain the key as described in the previous section.
Then use `rpm --import' to import the key.  For example, if you have
the public key stored in a file named `mysql_pubkey.asc', import it
using this command:

     shell> rpm --import mysql_pubkey.asc

Installation Layouts
--------------------

This section describes the default layout of the directories created by
installing binary or source distributions provided by MySQL AB. If you
install a distribution provided by another vendor, some other layout
might be used.

On Windows, the default installation directory is `C:\mysql', which has
the following subdirectories:

*Directory*               *Contents of Directory*
`bin'                     Client programs and the
                          `mysqld' server
`data'                    Log files, databases
`Docs'                    Documentation
`examples'                Example programs and scripts
`include'                 Include (header) files
`lib'                     Libraries
`scripts'                 Utility scripts
`share'                   Error message files

Installations created from Linux RPM distributions result in files under
the following system directories:

*Directory*               *Contents of Directory*
`/usr/bin'                Client programs and scripts
`/usr/sbin'               The `mysqld' server
`/var/lib/mysql'          Log files, databases
`/usr/share/doc/packages' Documentation
`/usr/include/mysql'      Include (header) files
`/usr/lib/mysql'          Libraries
`/usr/share/mysql'        Error message and character set
                          files
`/usr/share/sql-bench'    Benchmarks

On Unix, a `tar' file binary distribution is installed by unpacking it
at the installation location you choose (typically `/usr/local/mysql')
and creates the following directories in that location:

*Directory*               *Contents of Directory*
`bin'                     Client programs and the
                          `mysqld' server
`data'                    Log files, databases
`docs'                    Documentation, ChangeLog
`include'                 Include (header) files
`lib'                     Libraries
`scripts'                 `mysql_install_db'
`share/mysql'             Error message files
`sql-bench'               Benchmarks

A source distribution is installed after you configure and compile it.
By default, the installation step installs files under `/usr/local', in
the following subdirectories:

*Directory*               *Contents of Directory*
`bin'                     Client programs and scripts
`include/mysql'           Include (header) files
`info'                    Documentation in Info format
`lib/mysql'               Libraries
`libexec'                 The `mysqld' server
`share/mysql'             Error message files
`sql-bench'               Benchmarks and `crash-me' test
`var'                     Databases and log files

Within an installation directory, the layout of a source installation
differs from that of a binary installation in the following ways:

   * The `mysqld' server is installed in the `libexec' directory rather
     than in the `bin' directory.

   * The data directory is `var' rather than `data'.

   * `mysql_install_db' is installed in the `bin' directory rather than
     in the `scripts' directory.

   * The header file and library directories are `include/mysql' and
     `lib/mysql' rather than `include' and `lib'.

You can create your own binary installation from a compiled source
distribution by executing the `scripts/make_binary_distribution' script
from the top directory of the source distribution.

Standard MySQL Installation Using a Binary Distribution
=======================================================

This section covers the installation of MySQL on platforms where we
offer packages using the native packaging format of the respective
platform. (This is also known as performing a "binary install.")
However, binary distributions of MySQL are available for many other
platforms as well. See *Note Installing binary:: for generic
installation instructions for these packages that apply to all
platforms.

See *Note General Installation Issues:: for more information on what
other binary distributions are available and how to obtain them.

Installing MySQL on Windows
---------------------------

The installation process for MySQL on Windows has the following steps:

  1. Obtain and install the distribution.

  2. Set up an option file if necessary.

  3. Select the server you want to use.

  4. Start the server.

  5. Assign passwords to the initial MySQL accounts.


MySQL for Windows is available in two distribution formats:

   * The binary distribution contains a setup program that installs
     everything you need so that you can start the server immediately.

   * The source distribution contains all the code and support files
     for building the executables using the VC++ 6.0 compiler.


Generally speaking, you should use the binary distribution. It's
simpler, and you need no additional tools to get MySQL up and running.

This section describes how to install MySQL on Windows using a binary
distribution.  To install using a source distribution, see *Note
Windows source build::.

Windows System Requirements
...........................

To run MySQL on Windows, you need the following:

   * A 32-bit Windows operating system such as 9x, Me, NT, 2000, or XP.
     The NT family (Windows NT, 2000, and XP) permits you to run the
     MySQL server as a service. *Note NT start::.

   * TCP/IP protocol support.

   * A copy of the MySQL binary distribution for Windows, which can be
     downloaded from `http://dev.mysql.com/downloads/'.  *Note Getting
     MySQL::.

     Note: If you download the distribution via FTP, we recommend the
     use of an adequate FTP client with a resume feature to avoid
     corruption of files during the download process.

   * `WinZip' or other Windows tool that can read `.zip' files, to
     unpack the distribution file.

   * Enough space on the hard drive to unpack, install, and create the
     databases in accordance with your requirements.

   * If you plan to connect to the MySQL server via ODBC, you also need
     a Connector/ODBC driver. *Note ODBC Connector::.

   * If you need tables with a size larger than 4GB, install MySQL on
     an NTFS or newer filesystem. Don't forget to use `MAX_ROWS' and
     `AVG_ROW_LENGTH' when you create tables.  *Note `CREATE TABLE':
     CREATE TABLE.


Installing a Windows Binary Distribution
........................................

To install MySQL on Windows using a binary distribution, follow this
procedure:

  1. If you are working on a Windows NT, 2000, or XP machine, make sure
     that you have logged in as a user with administrator privileges.

  2. If you are doing an upgrade of an earlier MySQL installation, it
     is necessary to stop the current server.  On Windows NT, 2000, or
     XP machines, if you are running the server as a Windows service,
     stop it as follows from the command prompt:

          C:\> NET STOP MySQL

     If you plan to use a different server after the upgrade (for
     example, if you want to run `mysqld-max' rather than `mysqld'),
     remove the existing service:

          C:\> C:\mysql\bin\mysqld --remove

     You can reinstall the service to use the proper server after
     upgrading.

     If you are not running the MySQL server as a service, stop it like
     this:

          C:\> C:\mysql\bin\mysqladmin -u root shutdown

  3. Exit the `WinMySQLAdmin' program if it is running.

  4. Unzip the distribution file to a temporary directory.

  5. Run the `setup.exe' program to begin the installation process.  If
     you want to install MySQL into a location other than the default
     directory (`C:\mysql'), use the `Browse' button to specify your
     preferred directory. If you do not install MySQL into the default
     location, you will need to specify the location whenever you start
     the server. The easiest way to do this is to use an option file,
     as described in *Note Windows prepare environment::.

  6. Finish the install process.


*Important note:* Early alpha Windows distributions for MySQL 4.1 do
not contain an installer program.  A 4.1 distribution is a Zip file
that you just unzip in the location where you want to install MySQL.
For example, to install `mysql-4.1.1-alpha-win.zip' as `C:\mysql', unzip
the distribution file on the `C:' drive, then rename the resulting
`mysql-4.1.1-alpha' directory to `mysql'.

If you are upgrading to MySQL 4.1 from an earlier version, you will
want to preserve your existing `data' directory that contains the grant
tables in the `mysql' database and your own databases.  Before
installing 4.1, stop the server if it is running, and save your `data'
directory to another location. Then either rename the existing
`C:\mysql' directory or remove it.  Install 4.1 as described in the
preceding paragraph, and then replace its `data' directory with your
old `data' directory.  This will avoid the loss of your current
databases.  Start the new server and update the grant tables.  *Note
Upgrading-grant-tables::.

Please see *Note Windows troubleshooting:: if you encounter
difficulties during installation.

Preparing the Windows MySQL Environment
.......................................

If you need to specify startup options when you run the server, you can
indicate them on the command line or place them in an option file. For
options that will be used every time the server starts, you will find
it most convenient to use an option file to specify your MySQL
configuration. This is true particularly under the following
circumstances:

   * The installation or data directory locations are different from
     the default locations (`C:\mysql' and `C:\mysql\data').

   * You need to tune the server settings.  For example, to use the
     `InnoDB' transactional tables in MySQL 3.23, you must manually add
     some extra lines to the option file, as described in *Note
     `InnoDB' configuration: InnoDB configuration.  (As of MySQL 4.0,
     `InnoDB' creates its data files and log files in the data
     directory by default. This means you need not configure `InnoDB'
     explicitly.  You may still do so if you wish, and an option file
     will be useful in this case, too.)


On Windows, the MySQL installer places the data directory directly under
the directory where you install MySQL.  If you would like to use a data
directory in a different location, you should copy the entire contents
of the `data' directory to the new location. For example, by default,
the installer places MySQL in `C:\mysql' and the data directory in
`C:\mysql\data'. If you want to use a data directory of `E:\mydata',
you must do two things:

   * Move the data directory from `C:\mysql\data' to `E:\mydata'.

   * Use a `--datadir' option to specify the new data directory location
     each time you start the server.


When the MySQL server starts on Windows, it looks for options in two
files:  the `my.ini' file in the Windows directory, and the `C:\my.cnf'
file.  The Windows directory typically is named something like
`C:\WINDOWS' or `C:\WinNT'.  You can determine its exact location from
the value of the `WINDIR' environment variable using the following
command:

     C:\> echo %WINDIR%

MySQL looks for options first in the `my.ini' file, then in the
`my.cnf' file.  However, to avoid confusion, it's best if you use only
one file.  If your PC uses a boot loader where the `C:' drive isn't the
boot drive, your only option is to use the `my.ini' file.  Whichever
option file you use, it must be a plain text file.

An option file can be created and modified with any text editor, such
as the `Notepad' program.  For example, if MySQL is installed at
`E:\mysql' and the data directory is located at `E:\mydata\data', you
can create the option file and set up a `[mysqld]' section to specify
values for the `basedir' and `datadir' parameters:

     [mysqld]
     # set basedir to your installation path
     basedir=E:/mysql
     # set datadir to the location of your data directory
     datadir=E:/mydata/data

Note that Windows pathnames are specified in option files using forward
slashes rather than backslashes.  If you do use backslashes, you must
double them.

Another way to manage an option file is to use the `WinMySQLAdmin'
tool. You can find `WinMySQLAdmin' in the `bin' directory of your MySQL
installation, as well as a help file containing instructions for using
it. `WinMySQLAdmin' has the capability of editing your option file, but
note these points:

   * `WinMySQLAdmin' uses only the `my.ini' file.

   * If `WinMySQLAdmin' finds a `C:\my.cnf' file, it will in fact rename
     it to `C:\my_cnf.bak' to disable it.


Now you are ready to start the server.

Selecting a Windows Server
..........................

Starting with MySQL 3.23.38, the Windows distribution includes both the
normal and the MySQL-Max server binaries.

Up through the early releases of MySQL 4.1, the servers included in
Windows distributions are named like this:

*Binary*       *Description*
`mysqld'       Compiled with full debugging and automatic memory
               allocation checking, symbolic links, and `InnoDB' and
               `BDB' tables.
`mysqld-opt'   Optimized binary.  From version 4.0 on, `InnoDB' is
               enabled.  Before 4.0, this server includes no
               transactional table support.
`mysqld-nt'    Optimized binary for Windows NT, 2000, and XP with
               support for named pipes.
`mysqld-max'   Optimized binary with support for symbolic links, and
               `InnoDB' and `BDB' tables.
`mysqld-max-nt'Like `mysqld-max', but compiled with support for named
               pipes.

We have found that the server with the most generic name (`mysqld') is
the one that many users are likely to choose by default. However, that
is also the server that results in the highest memory and CPU use due
to the inclusion of full debugging support.  The server named
`mysqld-opt' is a better general-use server choice to make instead if
you don't need debugging suport and don't want the maximal feature set
offered by the `-max' servers or named pipe support offered by the
`-nt' servers.

To make it less likely that the debugging server would be chosen
inadvertantly, some name changes were made from MySQL 4.1.2 to 4.1.4:
`mysqld' has been renamed to `mysqld-debug' and `mysqld-opt' has been
renamed to `mysqld'.  Thus, the server that includes debugging support
indicates that in its name, and the server named `mysqld' is an
efficient default choice. The other servers still have their same
names. The resulting servers are named like this:

*Binary*       *Description*
`mysqld-debug' Compiled with full debugging and automatic memory
               allocation checking, symbolic links, and `InnoDB' and
               `BDB' tables.
`mysqld'       Optimized binary with `InnoDB' support.
`mysqld-nt'    Optimized binary for Windows NT, 2000, and XP with
               support for named pipes.
`mysqld-max'   Optimized binary with support for symbolic links, and
               `InnoDB' and `BDB' tables.
`mysqld-max-nt'Like `mysqld-max', but compiled with support for named
               pipes.

The name changes were not both instituted at the same time. If you have
MySQL 4.1.2 or 4.1.3, it might be that you have a server named
`mysqld-debug' but not one named `mysqld'. In this case, you should
have have a server `mysqld-opt', which you should choose as your
default server unless you need maximal features, named pipes, or
debugging support.

All of the preceding binaries are optimized for modern Intel processors,
but should work on any Intel i386-class or higher processor.

MySQL supports TCP/IP on all Windows platforms. The `mysqld-nt' and
`mysql-max-nt' servers support named pipes on NT, 2000, and XP.
However, the default is to use TCP/IP regardless of the platform.
(Named pipes are slower than TCP/IP in many Windows configurations.)
Named pipe use is subject to these conditions:

   * Starting from MySQL 3.23.50, named pipes are enabled only if you
     start the server with the `--enable-named-pipe' option.  It is now
     necessary to use this option explicitly because some users have
     experienced problems shutting down the MySQL server when named
     pipes were used.

   * Named pipe connections are allowed only by the `mysqld-nt' or
     `mysqld-max-nt' servers, and only if the server is run on a
     version of Windows that supports named pipes (NT, 2000, XP).

   * These servers can be run on Windows 98 or Me, but only if TCP/IP
     is installed; named pipe connections cannot be used.

   * On Windows 95, these servers cannot be used.


*Note*: Most of the examples in the following sections use `mysqld' as
the server name. If you choose to use a different server, such as
`mysqld-opt', make the appropriate substitutions in the commands that
are shown in the examples. One good reason to choose a different server
is that because `mysqld' contains full debugging support, it uses more
memory and runs slower than the other Windows servers.

Starting the Server for the First Time
......................................

On Windows 95, 98, or Me, MySQL clients always connect to the server
using TCP/IP.  (This will allow any machine on your network to connect
to your MySQL server.)  Because of this, you must make sure that TCP/IP
support is installed on your machine before starting MySQL.  You can
find TCP/IP on your Windows CD-ROM.

Note that if you are using an old Windows 95 release (for example,
OSR2), it's likely that you have an old Winsock package; MySQL requires
Winsock 2! You can get the newest Winsock from
`http://www.microsoft.com/'.  Windows 98 has the new Winsock 2 library,
so it is unnecessary to update the library.

On NT-based systems such as Windows NT, 2000, or XP, clients have two
options. They can use TCP/IP, or they can use a named pipe if the server
supports named pipe connections.

In MySQL 4.1 and up, Windows servers also support shared-memory
connections if started with the `--shared-memory' option.  Clients can
connect this way by using the `--protocol=memory' option.

For information about which server binary to run, see *Note Windows
select server::.

This section gives a general overview of starting the MySQL server.
The following sections provide more specific information for particular
versions of Windows.

The examples in these sections assume that MySQL is installed under the
default location of `C:\mysql'. Adjust the pathnames shown in the
examples if you have MySQL installed in a different location.

Testing is best done from a command prompt in a console window (a "DOS
window"). This way you can have the server display status messages in
the window where they are easy to see.  If something is wrong with your
configuration, these messages will make it easier for you to identify
and fix any problems.

To start the server, enter this command:

     C:\> C:\mysql\bin\mysqld --console

For servers that include `InnoDB' support, you should see the following
messages as the server starts:

     InnoDB: The first specified datafile c:\ibdata\ibdata1 did not exist:
     InnoDB: a new database to be created!
     InnoDB: Setting file c:\ibdata\ibdata1 size to 209715200
     InnoDB: Database physically writes the file full: wait...
     InnoDB: Log file c:\iblogs\ib_logfile0 did not exist: new to be created
     InnoDB: Setting log file c:\iblogs\ib_logfile0 size to 31457280
     InnoDB: Log file c:\iblogs\ib_logfile1 did not exist: new to be created
     InnoDB: Setting log file c:\iblogs\ib_logfile1 size to 31457280
     InnoDB: Log file c:\iblogs\ib_logfile2 did not exist: new to be created
     InnoDB: Setting log file c:\iblogs\ib_logfile2 size to 31457280
     InnoDB: Doublewrite buffer not found: creating new
     InnoDB: Doublewrite buffer created
     InnoDB: creating foreign key constraint system tables
     InnoDB: foreign key constraint system tables created
     011024 10:58:25  InnoDB: Started

When the server finishes its startup sequence, you should see something
like this, which indicates that the server is ready to service client
connections:

     mysqld: ready for connections
     Version: '4.0.14-log'  socket: ''  port: 3306

The server will continue to write to the console any further diagnostic
output it produces.  You can open a new console window in which to run
client programs.

If you omit the `--console' option, the server writes diagnostic output
to the error log in the data directory (`C:\mysql\data' by default).
The error log is the file with the `.err' extension.

*Note*: The accounts that are listed in the MySQL grant tables
initially have no passwords.  After starting the server, you should set
up passwords for them using the instructions in *Note
Post-installation::.

Starting MySQL from the Windows Command Line
............................................

The MySQL server can be started manually from the command line.  This
can be done on any version of Windows.

To start the `mysqld' server from the command line, you should start a
console window (a "DOS window") and enter this command:

     C:\> C:\mysql\bin\mysqld

On non-NT versions of Windows, this will start `mysqld' in the
background. That is, after the server starts, you should see another
command prompt. If you start the server this way on Windows NT, 2000,
or XP, the server will run in the foreground and no command prompt will
appear until the server exits.  Because of this, you should open
another console window to run client programs while the server is
running.

You can stop the MySQL server by executing this command:

     C:\> C:\mysql\bin\mysqladmin -u root shutdown

This invokes the MySQL administrative utility `mysqladmin' to connect
to the server and tell it to shut down. The command connects as `root',
which is the default administrative account in the MySQL grant system.
Note that users in the MySQL grant system are wholly independent from
any login users under Windows.

If `mysqld' doesn't start, check the error log to see whether the
server wrote any messages there to indicate the cause of the problem.
The error log is located in the `C:\mysql\data' directory. It is the
file with a suffix of `.err'. You can also try to start the server as
`mysqld --console'; in this case, you may get some useful information
on the screen that may help solve the problem.

The last option is to start `mysqld' with `--standalone --debug'.  In
this case, `mysqld' will write a log file `C:\mysqld.trace' that should
contain the reason why `mysqld' doesn't start. *Note Making trace
files::.

Use `mysqld --help' to display all the options that `mysqld'
understands!

Starting MySQL as a Windows Service
...................................

On the NT family (Windows NT, 2000, or XP), the recommended way to run
MySQL is to install it as a Windows service. Then Windows starts and
stops the MySQL server automatically when Windows starts and stops. A
server installed as a service can also be controlled from the command
line using `NET' commands, or with the graphical `Services' utility.

The `Services' utility (the Windows `Service Control Manager') can be
found in the Windows `Control Panel' (under `Administrative Tools' on
Windows 2000 or XP). It is advisable to close the `Services' utility
while performing server installation or removal operations from this
command line.  This prevents some odd errors.

To get MySQL to work with TCP/IP on Windows NT 4, you must install
service pack 3 (or newer).

Before installing MySQL as a Windows service, you should first stop the
current server if it is running by using the following command:

     C:\> C:\mysql\bin\mysqladmin -u root shutdown

This invokes the MySQL administrative utility `mysqladmin' to connect
to the server and tell it to shut down. The command connects as `root',
which is the default administrative account in the MySQL grant system.
Note that users in the MySQL grant system are wholly independent from
any login users under Windows.

Now install the server as a service:

     C:\> mysqld --install

If you have problems installing `mysqld' as a service using just the
server name, try installing it using its full pathname:

     C:\> C:\mysql\bin\mysqld --install

As of MySQL 4.0.2, you can specify a specific service name after the
`--install' option.  As of MySQL 4.0.3, you can in addition specify a
`--defaults-file' option after the service name to indicate where the
server should obtain options when it starts. The rules that determine
the service name and option files the server uses are as follows:

   * If you specify no service name, the server uses the default
     service name of `MySQL' and the server reads options from the
     `[mysqld]' group in the standard option files.

   * If you specify a service name after the `--install' option, the
     server ignores the `[mysqld]' option group and instead reads
     options from the group that has the same name as the service. The
     server reads options from the standard option files.

   * If you specify a `--defaults-file' option after the service name,
     the server ignores the standard option files and reads options
     only from the `[mysqld]' group of the named file.


*Note*: Prior to MySQL 4.0.17, a server installed as a Windows service
has problems starting if its pathname or the service name contains
spaces. For this reason, avoid installing MySQL in a directory such as
`C:\Program Files' or using a service name containing spaces.

In the usual case that you install the server with `--install' but no
service name, the server is installed with a service name of `MySQL'.

As a more complex example, consider the following command:

     C:\> C:\mysql\bin\mysqld --install mysql --defaults-file=C:\my-opts.cnf

Here, a service name is given after the `--install' option. If no
`--defaults-file' option had been given, this command would have the
effect of causing the server to read the `[mysql]' group from the
standard option files. (This would be a bad idea, because that option
group is for use by the `mysql' client program.) However, because the
`--defaults-file' option is present, the server reads options only from
the named file, and only from the `[mysqld]' option group.

You can also specify options as "`Start parameters'" in the Windows
`Services' utility before you start the MySQL service.

Once a MySQL server is installed as a service, Windows will start the
service automatically whenever Windows starts.  The service also can be
started immediately from the `Services' utility, or by using the
command `NET START MySQL'.  The `NET' command is not case sensitive.

When run as a service, `mysqld' has no access to a console window, so
no messages can be seen there.  If `mysqld' doesn't start, check the
error log to see whether the server wrote any messages there to
indicate the cause of the problem.  The error log is located in the
`C:\mysql\data' directory. It is the file with a suffix of `.err'.

When `mysqld' is running as a service, it can be stopped by using the
`Services' utility, the command `NET STOP MySQL', or the command
`mysqladmin shutdown'. If the service is running when Windows shuts
down, Windows will stop the server automatically.

From MySQL 3.23.44 on, you have the choice of installing the server as
a `Manual' service if you don't wish the service to be started
automatically during the boot process. To do this, use the
`--install-manual' option rather than the `--install' option:

     C:\> C:\mysql\bin\mysqld --install-manual

To remove a server that is installed as a service, first stop it if it
is running. Then use the `--remove' option to remove it:

     C:\> C:\mysql\bin\mysqld --remove

For MySQL versions older than 3.23.49, one problem with automatic MySQL
service shutdown is that Windows waited only for a few seconds for the
shutdown to complete, then killed the database server process if the
time limit was exceeded. This had the potential to cause problems.
(For example, the `InnoDB' storage engine had to perform crash recovery
at the next startup.) Starting from MySQL 3.23.49, Windows waits longer
for the MySQL server shutdown to complete. If you notice this still is
not enough for your installation, it is safest not to run the MySQL
server as a service. Instead, start it from the command-line prompt,
and stop it with `mysqladmin shutdown'.

This change to tell Windows to wait longer when stopping the MySQL
server works for Windows 2000 and XP. It does not work for Windows NT,
where Windows waits only 20 seconds for a service to shut down, and
after that kills the service process. You can increase this default by
opening the Registry Editor `\winnt\system32\regedt32.exe' and editing
the value of `WaitToKillServiceTimeout' at
`HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control' in the Registry
tree. Specify the new larger value in milliseconds.  For example, the
value 120000 tells Windows NT to wait up to 120 seconds.

If you don't want to start `mysqld' as a service, you can start it from
the command line.  For instructions, see *Note Win95 start::.

Please see *Note Windows troubleshooting:: if you encounter
difficulties during installation.

Troubleshooting a MySQL Installation Under Windows
..................................................

When installing and running MySQL for the first time, you may encounter
certain errors that prevent the MySQL server from starting.  The
purpose of this section is to help you diagnose and correct some of
these errors.

Your first resource when troubleshooting server issues is the error log.
The MySQL server uses the error log to record information relevant to
the error that is preventing the server from starting. The error log is
located in the data directory specified in your `my.ini' file.  The
default data directory location is `C:\mysql\data'.  *Note Error log::.

Another source of information regarding possible errors is the console
messages displayed when the MySQL service is starting. Use the `NET
START mysql' command from the command line after installing `mysqld' as
a service to see any error messages regarding the starting of the MySQL
server as a service.  *Note NT start::.

The following are examples of some of the more common error messages
you may encounter when installing MySQL and starting the server for the
first time:

     System error 1067 has occurred.
     Fatal error: Can't open privilege tables: Table 'mysql.host' doesn't exist

These messages occur when the MySQL server cannot find the `mysql'
privileges database or other critical files. This error is often
encountered when the MySQL base or data directories are installed in
different locations than the default locations (`C:\mysql' and
`C:\mysql\data', respectively).

If you have installed MySQL to a directory other than `C:\mysql' you
will need to ensure that the MySQL server is aware of this through the
use of a configuration (`my.ini') file. The `my.ini' file needs to be
located in your Windows directory, typically located at `C:\WinNT' or
`C:\WINDOWS'. You can determine its exact location from the value of
the `WINDIR' environment variable by issuing the following command from
the command prompt:

     C:\> echo %WINDIR%

An option file can be created and modified with any text editor, such
as the Notepad program. For example, if MySQL is installed at
`E:\mysql' and the data directory is located at `D:\MySQLdata', you can
create the option file and set up a `[mysqld]' section to specify
values for the basedir and datadir parameters:

     [mysqld]
     # set basedir to your installation path
     basedir=E:/mysql
     # set datadir to the location of your data directory
     datadir=D:/MySQLdata

Note that Windows pathnames are specified in option files using forward
slashes rather than backslashes. If you do use backslashes, you must
double them:

     [mysqld]
     # set basedir to your installation path
     basedir=C:\\Program Files\\mysql
     # set datadir to the location of your data directory
     datadir=D:\\MySQLdata
*Note Windows prepare environment::.

Running MySQL Client Programs on Windows
........................................

You can test whether the MySQL server is working by executing any of the
following commands:

     C:\> C:\mysql\bin\mysqlshow
     C:\> C:\mysql\bin\mysqlshow -u root mysql
     C:\> C:\mysql\bin\mysqladmin version status proc
     C:\> C:\mysql\bin\mysql test

If `mysqld' is slow to respond to TCP/IP connections from client
programs on Windows 9x/Me, there is probably a problem with your DNS.
In this case, start `mysqld' with the `--skip-name-resolve' option and
use only `localhost' and IP numbers in the `Host' column of the MySQL
grant tables.

You can force a MySQL client to use a named pipe connection rather than
TCP/IP  by specifying the `--pipe' option or by specifying `.' (period)
as the host name.  Use the `--socket' option to specify the name of the
pipe.  As of MySQL 4.1, you should use the `--protocol=PIPE' option.

There are two versions of the MySQL command-line tool:
*Binary*       *Description*
`mysql'        Compiled on native Windows, offering limited text editing
               capabilities.
`mysqlc'       Compiled with the Cygnus GNU compiler and libraries,
               which offers `readline' editing.

If you want to use `mysqlc', you must have a copy of the
`cygwinb19.dll' library installed somewhere that `mysqlc' can find it.
Current distributions of MySQL include this library in the same
directory as `mysqlc' (the `bin' directory under the base directory of
your MySQL installation). If your distribution does not have the
`cygwinb19.dll' library in the `bin' directory, look for it in the
`lib' directory and copy it to your Windows system directory
(`\Windows\system' or a similar place).

MySQL on Windows Compared to MySQL on Unix
..........................................

MySQL for Windows has by now proven itself to be very stable. The
Windows version of MySQL has the same features as the corresponding
Unix version, with the following exceptions:

*Windows 95 and threads*
     Windows 95 leaks about 200 bytes of main memory for each thread
     creation.  Each connection in MySQL creates a new thread, so you
     shouldn't run `mysqld' for an extended time on Windows 95 if your
     server handles many connections!  Other versions of Windows don't
     suffer from this bug.

*Limited number of ports*
     Windows systems have about 4,000 ports available for client
     connections, and after a connection on a port closes, it takes two
     to four minutes before the port can be reused.  In situations
     where clients connect to and disconnect from the server at a high
     rate, it is possible for all available ports to be used up before
     closed ports become available again. If this happens, the MySQL
     server will appear to have become unresponsive even though it is
     running.  Note that ports may be used by other applications
     running on the machine as well, in which case the number of ports
     available to MySQL is lower.

     For more information, see
     `http://support.microsoft.com/default.aspx?scid=kb;en-us;196271'.

*Concurrent reads*
     MySQL depends on the `pread()' and `pwrite()' calls to be able to
     mix `INSERT' and `SELECT'.  Currently we use mutexes to emulate
     `pread()'/`pwrite()'.  We will, in the long run, replace the file
     level interface with a virtual interface so that we can use the
     `readfile()'/`writefile()' interface on NT, 2000, and XP to get
     more speed.  The current implementation limits the number of open
     files MySQL can use to 2,048 (1,024 before MySQL 4.0.19), which
     means that you will not be able to run as many concurrent threads
     on NT, 2000, and XP as on Unix.

*Blocking read*
     MySQL uses a blocking read for each connection, which has the
     following implications if named pipe connections are enabled:

        * A connection will not be disconnected automatically after
          eight hours, as happens with the Unix version of MySQL.

        * If a connection hangs, it's impossible to break it without
          killing MySQL.

        * `mysqladmin kill' will not work on a sleeping connection.

        * `mysqladmin shutdown' can't abort as long as there are
          sleeping connections.

     We plan to fix this problem when our Windows developers have
     figured out a nice workaround.

*`ALTER TABLE'*
     While you are executing an `ALTER TABLE' statement, the table is
     locked from being used by other threads.  This has to do with the
     fact that on Windows, you can't delete a file that is in use by
     another thread.  In the future, we may find some way to work
     around this problem.

*`DROP TABLE'*
     `DROP TABLE' on a table that is in use by a `MERGE' table will not
     work on Windows because the `MERGE' handler does the table mapping
     hidden from the upper layer of MySQL.  Because Windows doesn't
     allow you to drop files that are open, you first must flush all
     `MERGE' tables (with `FLUSH TABLES') or drop the `MERGE' table
     before dropping the table.  We will fix this at the same time we
     introduce views.

*`DATA DIRECTORY' and `INDEX DIRECTORY'*
     The `DATA DIRECTORY' and `INDEX DIRECTORY' options for `CREATE
     TABLE' are ignored on Windows, because Windows doesn't support
     symbolic links.  These options also are ignored on systems that
     have a non-functional `realpath()' call.

*`DROP DATABASE'*
     You cannot drop a database that is in use by some thread.

*Killing MySQL from the Task Manager*
     You cannot kill MySQL from the Task Manager or with the shutdown
     utility in Windows 95.  You must take it down with `mysqladmin
     shutdown'.

*Case-insensitive names*
     Filenames are not case sensitive on Windows, so MySQL database and
     table names are also not case sensitive on Windows.  The only
     restriction is that database and table names must be specified
     using the same case throughout a given statement.  *Note Name case
     sensitivity::.

*The `\' pathname separator character*
     Pathname components in Windows 95 are separated by the `\'
     character, which is also the escape character in MySQL.  If you
     are using `LOAD DATA INFILE' or `SELECT ... INTO OUTFILE', use
     Unix-style filenames with `/' characters:

          mysql> LOAD DATA INFILE 'C:/tmp/skr.txt' INTO TABLE skr;
          mysql> SELECT * INTO OUTFILE 'C:/tmp/skr.txt' FROM skr;

     Alternatively, you must double the `\' character:

          mysql> LOAD DATA INFILE 'C:\\tmp\\skr.txt' INTO TABLE skr;
          mysql> SELECT * INTO OUTFILE 'C:\\tmp\\skr.txt' FROM skr;

*Problems with pipes.*
     Pipes do not work reliably from the Windows command-line prompt.
     If the pipe includes the character `^Z' / `CHAR(24)', Windows will
     think it has encountered end-of-file and abort the program.

     This is mainly a problem when you try to apply a binary log as
     follows:

          C:\> mysqlbinlog binary-log-name | mysql --user=root

     If you have a problem applying the log and suspect that it is
     because of a `^Z' / `CHAR(24)' character, you can use the
     following workaround:

          C:\> mysqlbinlog binary-log-file --result-file=/tmp/bin.sql
          C:\> mysql --user=root --execute "source /tmp/bin.sql"

     The latter command also can be used to reliably read in any SQL
     file that may contain binary data.

*`Can't open named pipe' error*
     If you use a MySQL 3.22 server on Windows NT with the newest MySQL
     client programs, you will get the following error:

          error 2017: can't open named pipe to host: . pipe...

     This happens because the release version of MySQL uses named pipes
     on NT by default.  You can avoid this error by using the
     `--host=localhost' option to the new MySQL clients or by creating
     an option file `C:\my.cnf' that contains the following information:

          [client]
          host = localhost

     Starting from 3.23.50, named pipes are enabled only if `mysqld-nt'
     or `mysqld-max-nt' is started with `--enable-named-pipe'.

*`Access denied for user' error*
     If you attempt to run a MySQL client program to connect to a server
     running on the same machine, but get the error `Access denied for
     user 'SOME-USER'@'unknown' to database 'mysql'', this means that
     MySQL cannot resolve your hostname properly.

     To fix this, you should create a file named `\windows\hosts'
     containing the following information:

          127.0.0.1       localhost

Here are some open issues for anyone who might want to help us improve
MySQL on Windows:

   * Add some nice start and shutdown icons to the MySQL installation.

   * It would be really nice to be able to kill `mysqld' from the Task
     Manager in Windows 95.  For the moment, you must use `mysqladmin
     shutdown'.

   * Port `readline' to Windows for use in the `mysql' command-line
     tool.

   * GUI versions of the standard MySQL clients (`mysql', `mysqlshow',
     `mysqladmin', and `mysqldump') would be nice.

   * It would be nice if the socket read and write functions in `net.c'
     were interruptible. This would make it possible to kill open
     threads with `mysqladmin kill' on Windows.

   * Add macros to use the faster thread-safe increment/decrement
     methods provided by Windows.

Installing MySQL on Linux
-------------------------

The recommended way to install MySQL on Linux is by using the RPM
packages. The MySQL RPMs are currently built on a SuSE Linux 7.3
system, but should work on most versions of Linux that support `rpm'
and use `glibc'.  To obtain RPM packages, see *Note Getting MySQL::.

*Note*: RPM distributions of MySQL often are provided by other vendors.
Be aware that they may differ in features and capabilities from those
built by MySQL AB, and that the instructions in this manual do not
necessarily apply to installing them. The vendor's instructions should
be consulted instead.

If you have problems with an RPM file (for example, if you receive the
error "`Sorry, the host 'XXXX' could not be looked up'"), see *Note
Binary notes-Linux::.

In most cases, you only need to install the `MySQL-server' and
`MySQL-client' packages to get a functional MySQL installation. The
other packages are not required for a standard installation.  If you
want to run a MySQL-Max server that has additional capabilities, you
should also install the `MySQL-Max' RPM. However, you should do so only
_ after_ installing the `MySQL-server' RPM.  *Note `mysqld-max':
mysqld-max.

If you get a dependency failure when trying to install the MySQL 4.0
packages (for example, "`error: removing these packages would break
dependencies: libmysqlclient.so.10 is needed by ...'"), you should also
install the package `MySQL-shared-compat', which includes both the
shared libraries for backward compatibility (`libmysqlclient.so.12' for
MySQL 4.0 and `libmysqlclient.so.10' for MySQL 3.23).

Many Linux distributions still ship with MySQL 3.23 and they usually
link applications dynamically to save disk space. If these shared
libraries are in a separate package (for example, `MySQL-shared'), it is
sufficient to simply leave this package installed and just upgrade the
MySQL server and client packages (which are statically linked and do
not depend on the shared libraries). For distributions that include the
shared libraries in the same package as the MySQL server (for example,
Red Hat Linux), you could either install our 3.23 `MySQL-shared' RPM,
or use the `MySQL-shared-compat' package instead.

The following RPM packages are available:

   * `MySQL-server-VERSION.i386.rpm'

     The MySQL server.  You will need this unless you only want to
     connect to a MySQL server running on another machine. Note: Server
     RPM files were called `MySQL-VERSION.i386.rpm' before MySQL
     4.0.10. That is, they did not have `-server' in the name.

   * `MySQL-Max-VERSION.i386.rpm'

     The MySQL-Max server. This server has additional capabilities that
     the one provided in the `MySQL-server' RPM does not.  You must
     install the `MySQL-server' RPM first, because the `MySQL-Max' RPM
     depends on it.

   * `MySQL-client-VERSION.i386.rpm'

     The standard MySQL client programs. You probably always want to
     install this package.

   * `MySQL-bench-VERSION.i386.rpm'

     Tests and benchmarks. Requires Perl and the `DBD::mysql' module.

   * `MySQL-devel-VERSION.i386.rpm'

     The libraries and include files that are needed if you want to
     compile other MySQL clients, such as the Perl modules.

   * `MySQL-shared-VERSION.i386.rpm'

     This package contains the shared libraries (`libmysqlclient.so*')
     that certain languages and applications need to dynamically load
     and use MySQL.

   * `MySQL-shared-compat-VERSION.i386.rpm'

     This package includes the shared libraries for both MySQL 3.23 and
     MySQL 4.0. Install this package instead of `MySQL-shared' if you
     have applications installed that are dynamically linked against
     MySQL 3.23 but you want to upgrade to MySQL 4.0 without breaking
     the library dependencies. This package has been available since
     MySQL 4.0.13.

   * `MySQL-embedded-VERSION.i386.rpm'

     The embedded MySQL server library (from MySQL 4.0).

   * `MySQL-VERSION.src.rpm'

     This contains the source code for all of the previous packages. It
     can also be used to rebuild the RPMs on other architectures (for
     example, Alpha or SPARC).

To see all files in an RPM package (for example, a `MySQL-server' RPM),
run:

     shell> rpm -qpl MySQL-server-VERSION.i386.rpm

To perform a standard minimal installation, run:

     shell> rpm -i MySQL-server-VERSION.i386.rpm
     shell> rpm -i MySQL-client-VERSION.i386.rpm

To install just the client package, run:

     shell> rpm -i MySQL-client-VERSION.i386.rpm

RPM provides a feature to verify the integrity and authenticity of
packages before installing them. If you would like to learn more about
this feature, see *Note Verifying Package Integrity::.

The server RPM places data under the `/var/lib/mysql' directory. The
RPM also creates a login account for a user named `mysql' (if one does
not already exist) to use for running the MySQL server, and creates the
appropriate entries in `/etc/init.d/' to start the server automatically
at boot time. (This means that if you have performed a previous
installation and have made changes to its startup script, you may want
to make a copy of the script so that you don't lose it when you install
a newer RPM.) See *Note Automatic start:: for more information on how
MySQL can be started automatically on system startup.

If you want to install the MySQL RPM on older Linux distributions that
do not support initialization scripts in `/etc/init.d' (directly or via
a symlink), you should create a symbolic link that points to the
location where your initialization scripts actually are installed. For
example, if that location is `/etc/rc.d/init.d', use these commands
before installing the RPM to create `/etc/init.d' as a symbolic link
that points there:

     shell> cd /etc
     shell> ln -s rc.d/init.d .

However, all current major Linux distributions should already support
the new directory layout that uses `/etc/init.d', because it is
required for LSB (Linux Standard Base) compliance.

If the RPM files that you install include `MySQL-server', the `mysqld'
server should be up and running after installation.  You should now be
able to start using MySQL.

If something goes wrong, you can find more information in the binary
installation section. *Note Installing binary::.

*Note*: The accounts that are listed in the MySQL grant tables
initially have no passwords.  After starting the server, you should set
up passwords for them using the instructions in *Note
Post-installation::.

Installing MySQL on Mac OS X
----------------------------

Beginning with MySQL 4.0.11, you can install MySQL on Mac OS X 10.2.x
("Jaguar") and up using a Mac OS X binary package in PKG format instead
of the binary tarball distribution. Please note that older versions of
Mac OS X (for example, 10.1.x) are not supported by this package.

The package is located inside a disk image (`.dmg') file that you first
need to mount by double-clicking its icon in the Finder. It should then
mount the image and display its contents.

To obtain MySQL, see *Note Getting MySQL::.

*Note*: Before proceeding with the installation, be sure to shut down
all running MySQL server instances by either using the MySQL Manager
Application (on Mac OS X Server) or via `mysqladmin shutdown' on the
command line.

To actually install the MySQL PKG file, double-click on the package
icon. This launches the Mac OS X Package Installer, which will guide
you through the installation of MySQL.

Due to a bug in the Mac OS X package installer, you may see this error
message in the destination disk selection dialog:

     You cannot install this software on this disk. (null)

If this error occurs, simply click the `Go Back' button once to return
to the previous screen. Then click `Continue' to advance to the
destination disk selection again, and you should be able to choose the
destination disk correctly. We have reported this bug to Apple and it is
investigating this problem.

The Mac OS X PKG of MySQL will install itself into
`/usr/local/mysql-VERSION' and will also install a symbolic link,
`/usr/local/mysql', pointing to the new location. If a directory named
`/usr/local/mysql' already exists, it will be renamed to
`/usr/local/mysql.bak' first. Additionally, the installer will create
the grant tables in the `mysql' database by executing `mysql_install_db'
after the installation.

The installation layout is similar to that of a `tar' file binary
distribution; all MySQL binaries are located in the directory
`/usr/local/mysql/bin'.  The MySQL socket file is created as
`/tmp/mysql.sock' by default.  *Note Installation layouts::.

MySQL installation requires a Mac OS X user account named `mysql'.  A
user account with this name should exist by default on Mac OS X 10.2
and up.

If you are running Mac OS X Server, you already have a version of MySQL
installed.  The versions of MySQL that ship with Mac OS X Server
versions are shown in the following table:

*Mac OS X Server       *MySQL Version*
Version*
10.2-10.2.2            3.23.51
10.2.3-10.2.6          3.23.53
10.3                   4.0.14
10.3.2                 4.0.16

This manual section covers the installation of the official MySQL Mac
OS X PKG only.  Make sure to read Apple's help information about
installing MySQL: Run the "Help View" application, select "Mac OS X
Server" help, do a search for "MySQL," and read the item entitled
"Installing MySQL."

For pre-installed versions of MySQL on Mac OS X Server, note especially
that you should start `mysqld' with `safe_mysqld' instead of
`mysqld_safe' if MySQL is older than version 4.0.

If you previously used Marc Liyanage's MySQL packages for Mac OS X from
`http://www.entropy.ch', you can simply follow the update instructions
for packages using the binary installation layout as given on his pages.

If you are upgrading from Marc's 3.23.xx versions or from the Mac OS X
Server version of MySQL to the official MySQL PKG, you also need to
convert the existing MySQL privilege tables to the current format,
because some new security privileges have been added.  *Note
Upgrading-grant-tables::.

If you would like to automatically start up MySQL during system
startup, you also need to install the MySQL Startup Item. Starting with
MySQL 4.0.15, it is part of the Mac OS X installation disk images as a
separate installation package. Simply double-click the
`MySQLStartupItem.pkg' icon and follow the instructions to install it.

Note that the Startup Item need be installed only once! There is no
need to install it each time you upgrade the MySQL package later.

The Startup Item will be installed into
`/Library/StartupItems/MySQLCOM'.  (Before MySQL 4.1.2, the location
was `/Library/StartupItems/MySQL', but that collided with the MySQL
Startup Item installed by Mac OS X Server.)  Startup Item installation
adds a variable `MYSQLCOM=-YES-' to the system configuration file
`/etc/hostconfig'. If you would like to disable the automatic startup
of MySQL, simply change this variable to `MYSQLCOM=-NO-'.

On Mac OS X Server, the default MySQL installation uses the variable
`MYSQL' in the `/etc/hostconfig' file.  The MySQL AB Startup Item
installer disables this variable by setting it to `MYSQL=-NO-'. This
avoids boot time conflicts with the `MYSQLCOM' variable used by the
MySQL AB Startup Item.  However, it does not shut down an already
running MySQL server. You should do that yourself.

After the installation, you can start up MySQL by running the following
commands in a terminal window. You must have administrator privileges to
perform this task.

If you have installed the Startup Item:

     shell> sudo /Library/StartupItems/MySQLCOM/MySQLCOM start
     (Enter your password, if necessary)
     (Press Control-D or enter "exit" to exit the shell)

For versions of MySQL older than 4.1.3, substitute
`/Library/StartupItems/MySQLCOM/MySQLCOM' with
`/Library/StartupItems/MySQL/MySQL' above.

If you don't use the Startup Item, enter the following command sequence:

     shell> cd /usr/local/mysql
     shell> sudo ./bin/mysqld_safe
     (Enter your password, if necessary)
     (Press Control-Z)
     shell> bg
     (Press Control-D or enter "exit" to exit the shell)

You should now be able to connect to the MySQL server, for example, by
running `/usr/local/mysql/bin/mysql'.

*Note*: The accounts that are listed in the MySQL grant tables
initially have no passwords.  After starting the server, you should set
up passwords for them using the instructions in *Note
Post-installation::.

You might want to add aliases to your shell's resource file to make it
easier to access commonly used programs such as `mysql' and `mysqladmin'
from the command line. The syntax for `tcsh' is:

     alias mysql /usr/local/mysql/bin/mysql
     alias mysqladmin /usr/local/mysql/bin/mysqladmin

For `bash', use:

     alias mysql=/usr/local/mysql/bin/mysql
     alias mysqladmin=/usr/local/mysql/bin/mysqladmin

Even better, add `/usr/local/mysql/bin' to your `PATH' environment
variable. For example, add the following line to your `$HOME/.tcshrc'
file if your shell is `tcsh':

     setenv PATH ${PATH}:/usr/local/mysql/bin

If no `.tcshrc' file exists in your home directory, create it with a
text editor.

If you are upgrading an existing installation, please note that
installing a new MySQL PKG does not remove the directory of an older
installation. Unfortunately, the Mac OS X Installer does not yet offer
the functionality required to properly upgrade previously installed
packages.

To use your existing databases with the new installation, you'll need
to copy the contents of the old data directory to the new data
directory. Make sure that neither the old server nor the new one is
running when you do this.  After you have copied over the MySQL
database files from the previous installation and have successfully
started the new server, you should consider removing the old
installation files to save disk space.  Additionally, you should also
remove older versions of the Package Receipt directories located in
`/Library/Receipts/mysql-VERSION.pkg'.

Installing MySQL on NetWare
---------------------------

Porting MySQL to NetWare was an effort spearheaded by Novell. Novell
customers will be pleased to note that NetWare 6.5 ships with bundled
MySQL binaries, complete with an automatic commercial use license for
all servers running that version of NetWare.

MySQL for NetWare is compiled using a combination of `Metrowerks
CodeWarrior for NetWare' and special cross-compilation versions of the
GNU autotools.

The latest binary packages for NetWare can be obtained at
`http://dev.mysql.com/downloads/'.  *Note Getting MySQL::.

In order to host MySQL, the NetWare server must meet these requirements:

   * NetWare 6.5 Support Pack 2 installed and updated with the latest
     LibC, or NetWare 6.0 with Support Pack 4 installed and updated
     with the latest LibC.  NetWare 6.5 Support Pack 2 and other
     updates are available at
     `http://support.novell.com/filefinder/18197/index.html'.  NetWare
     6.0 Support Pack 4 and other updates are available at
     `http://support.novell.com/filefinder/13659/index.html'.  The
     latest LibC is available at
     `http://developer.novell.com/ndk/libc.htm'.  Steps to update LibC
     can be found here:
     `http://developer.novell.com/ndk/doc/libc/index.html?page=/ndk/doc/libc/libc_enu/data/ajjl0r0.html'

   * The system must meet Novell's minimum requirements to run the
     respective version of NetWare.

   * MySQL data, as well as the binaries themselves, must be installed
     on an NSS volume; traditional volumes are not supported.

To install MySQL for NetWare, use the following procedure:

  1. If you are upgrading from a prior installation, stop the MySQL
     server.  This is done from the server console, using the following
     command:

          SERVER:  mysqladmin -u root shutdown

  2. Log on to the target server from a client machine with access to
     the location where you will install MySQL.

  3. Extract the binary package Zip file onto the server. Be sure to
     allow the paths in the Zip file to be used. It is safe to simply
     extract the file to `SYS:\'.

     If you are upgrading from a prior installation, you may need to
     copy the data directory (for example, `SYS:MYSQL\DATA') now, as
     well as `my.cnf', if you have customized it. You can then delete
     the old copy of MySQL.

  4. You might want to rename the directory to something more
     consistent and easy to use. We recommend using `SYS:MYSQL';
     examples in this manual use this name to refer to the installation
     directory in general.

  5. At the server console, add a search path for the directory
     containing the MySQL NLMs. For example:

          SERVER:  SEARCH ADD SYS:MYSQL\BIN

  6. Initialize the data directory and the grant tables, if needed, by
     executing `mysql_install_db' at the server console.

  7. Start the MySQL server using `mysqld_safe' at the server console.

  8. To finish the installation, you should also add the following
     commands to `autoexec.ncf'. For example, if your MySQL
     installation is in `SYS:MYSQL' and you want MySQL to start
     automatically, you could add these lines:

          #Starts the MySQL 4.0.x database server
          SEARCH ADD SYS:MYSQL\BIN
          MYSQLD_SAFE

     If you are running MySQL on NetWare 6.0, we strongly suggest that
     you use the `--skip-external-locking' option on the command line:

          #Starts the MySQL 4.0.x database server
          SEARCH ADD SYS:MYSQL\BIN
          MYSQLD_SAFE --skip-external-locking

     It will also be necessary to use `CHECK TABLE' and `REPAIR TABLE'
     instead of `myisamchk', because `myisamchk' makes use of external
     locking.  External locking is known to have problems on NetWare
     6.0; the problem has been eliminated in NetWare 6.5.

     `mysqld_safe' on NetWare provides a screen presence. When you
     unload (shut down) the `mysqld_safe' NLM, the screen does not by
     default go away.  Instead, it prompts for user input:

          *<NLM has terminated; Press any key to close the screen>*

     If you want NetWare to close the screen automatically instead, use
     the `--autoclose' option to `mysqld_safe'. For example:

          #Starts the MySQL 4.0.x database server
          SEARCH ADD SYS:MYSQL\BIN
          MYSQLD_SAFE --autoclose

  9. The latest Netware Perl and PHP modules for MySQL can be
     downloaded from `http://developer.novell.com/ndk/perl5.htm' and
     `http://developer.novell.com/ndk/php2.htm' respectively.


The behavior of `mysqld_safe' on NetWare is described further in *Note
`mysqld_safe': mysqld_safe.

If there was an existing installation of MySQL on the server, be sure
to check for existing MySQL startup commands in `autoexec.ncf', and
edit or delete them as necessary.

*Note*: The accounts that are listed in the MySQL grant tables
initially have no passwords.  After starting the server, you should set
up passwords for them using the instructions in *Note
Post-installation::.

Installing MySQL on Other Unix-Like Systems
-------------------------------------------

This section covers the installation of MySQL binary distributions that
are provided for various platforms in the form of compressed `tar' files
(files with a `.tar.gz' extension).  See *Note MySQL binaries:: for a
detailed list.

To obtain MySQL, see *Note Getting MySQL::.

MySQL `tar' file binary distributions have names of the form
`mysql-VERSION-OS.tar.gz', where `VERSION' is a number (for example,
`4.0.17'), and OS indicates the type of operating system for which the
distribution is intended (for example, `pc-linux-i686').

In addition to these generic packages, we also offer binaries in
platform-specific package formats for selected platforms.  See *Note
Quick Standard Installation:: for more information on how to install
these.

You need the following tools to install a MySQL `tar' file binary
distribution:

   * GNU `gunzip' to uncompress the distribution.

   * A reasonable `tar' to unpack the distribution. GNU `tar' is known
     to work. Some operating systems come with a pre-installed version
     of `tar' that is known to have problems.  For example, Mac OS X
     `tar' and Sun `tar' are known to have problems with long
     filenames.  On Mac OS X, you can use the pre-installed `gnutar'
     program.  On other systems with a deficient `tar', you should
     install GNU `tar' first.

If you run into problems, _please always use `mysqlbug'_ when posting
questions to a MySQL mailing list.  Even if the problem isn't a bug,
`mysqlbug' gathers system information that will help others solve your
problem.  By not using `mysqlbug', you lessen the likelihood of getting
a solution to your problem.  You will find `mysqlbug' in the `bin'
directory after you unpack the distribution.  *Note Bug reports::.

The basic commands you must execute to install and use a MySQL binary
distribution are:

     shell> groupadd mysql
     shell> useradd -g mysql mysql
     shell> cd /usr/local
     shell> gunzip < /PATH/TO/MYSQL-VERSION-OS.tar.gz | tar xvf -
     shell> ln -s FULL-PATH-TO-MYSQL-VERSION-OS mysql
     shell> cd mysql
     shell> scripts/mysql_install_db --user=mysql
     shell> chown -R root  .
     shell> chown -R mysql data
     shell> chgrp -R mysql .
     shell> bin/mysqld_safe --user=mysql &

For versions of MySQL older than 4.0, substitute `bin/safe_mysqld' for
`bin/mysqld_safe' in the final command.

*Note*: This procedure does not set up any passwords for MySQL
accounts.  After following the procedure, proceed to *Note
Post-installation::.

A more detailed version of the preceding description for installing a
binary distribution follows:

  1. Add a login user and group for `mysqld' to run as:

          shell> groupadd mysql
          shell> useradd -g mysql mysql

     These commands add the `mysql' group and the `mysql' user.  The
     syntax for `useradd' and `groupadd' may differ slightly on
     different versions of Unix.  They may also be called `adduser' and
     `addgroup'.

     You might want to call the user and group something else instead
     of `mysql'.  If so, substitute the appropriate name in the
     following steps.

  2. Pick the directory under which you want to unpack the
     distribution, and change location into it. In the following
     example, we unpack the distribution under `/usr/local'. (The
     instructions, therefore, assume that you have permission to create
     files and directories in `/usr/local'.  If that directory is
     protected, you will need to perform the installation as `root'.)

          shell> cd /usr/local

  3. Obtain a distribution file from one of the sites listed in *Note
     Getting MySQL: Getting MySQL.  For a given release, binary
     distributions for all platforms are built from the same MySQL
     source distribution.

  4. Unpack the distribution, which will create the installation
     directory.  Then create a symbolic link to that directory:

          shell> gunzip < /PATH/TO/MYSQL-VERSION-OS.tar.gz | tar xvf -
          shell> ln -s FULL-PATH-TO-MYSQL-VERSION-OS mysql

     The `tar' command creates a directory named `mysql-VERSION-OS'.
     The `ln' command makes a symbolic link to that directory.  This
     lets you refer more easily to the installation directory as
     `/usr/local/mysql'.

     With GNU `tar', no separate invocation of `gunzip' is necessary.
     You can replace the first line with the following alternative
     command to uncompress and extract the distribution:

          shell> tar zxvf /PATH/TO/MYSQL-VERSION-OS.tar.gz

  5. Change location into the installation directory:

          shell> cd mysql

     You will find several files and subdirectories in the `mysql'
     directory.  The most important for installation purposes are the
     `bin' and `scripts' subdirectories.

    `bin'
          This directory contains client programs and the server.  You
          should add the full pathname of this directory to your `PATH'
          environment variable so that your shell finds the MySQL
          programs properly. *Note Environment variables::.

    `scripts'
          This directory contains the `mysql_install_db' script used to
          initialize the `mysql' database containing the grant tables
          that store the server access permissions.

  6. If you haven't installed MySQL before, you must create the MySQL
     grant tables:

          shell> scripts/mysql_install_db --user=mysql

     If you run the command as `root', you should use the `--user'
     option as shown.  The value of the option should be the name of
     the login account that you created in the first step to use for
     running the server.  If you run the command while logged in as
     that user, you can omit the `--user' option.

     Note that for MySQL versions older than 3.22.10,
     `mysql_install_db' left the server running after creating the grant
     tables.  This is no longer true; you will need to restart the
     server after performing the remaining steps in this procedure.

  7. Change the ownership of program binaries to `root' and ownership
     of the data directory to the user that you will run `mysqld' as.
     Assuming that you are located in the installation directory
     (`/usr/local/mysql'), the commands look like this:

          shell> chown -R root  .
          shell> chown -R mysql data
          shell> chgrp -R mysql .

     The first command changes the owner attribute of the files to the
     `root' user. The second changes the owner attribute of the data
     directory to the `mysql' user. The third changes the group
     attribute to the `mysql' group.

  8. If you would like MySQL to start automatically when you boot your
     machine, you can copy `support-files/mysql.server' to the location
     where your system has its startup files.  More information can be
     found in the `support-files/mysql.server' script itself and in
     *Note Automatic start::.

  9. You can set up new accounts using the `bin/mysql_setpermission'
     script if you install the `DBI' and `DBD::mysql' Perl modules.
     For instructions, see *Note Perl support::.

 10. If you would like to use `mysqlaccess' and have the MySQL
     distribution in some non-standard place, you must change the
     location where `mysqlaccess' expects to find the `mysql' client.
     Edit the `bin/mysqlaccess' script at approximately line 18.
     Search for a line that looks like this:

          $MYSQL     = '/usr/local/bin/mysql';    # path to mysql executable

     Change the path to reflect the location where `mysql' actually is
     stored on your system.  If you do not do this, you will get a
     `Broken pipe' error when you run `mysqlaccess'.


After everything has been unpacked and installed, you should test your
distribution.

You can start the MySQL server with the following command:

     shell> bin/mysqld_safe --user=mysql &

For versions of MySQL older than 4.0, substitute `bin/safe_mysqld' for
`bin/mysqld_safe' in the command.

More information about `mysqld_safe' is given in *Note `mysqld_safe':
mysqld_safe.

*Note*: The accounts that are listed in the MySQL grant tables
initially have no passwords.  After starting the server, you should set
up passwords for them using the instructions in *Note
Post-installation::.

MySQL Installation Using a Source Distribution
==============================================

Before you proceed with the source installation, check first to see
whether our binary is available for your platform and whether it will
work for you. We put a lot of effort into making sure that our binaries
are built with the best possible options.

To obtain a source distribution for MySQL, *Note Getting MySQL::.

MySQL source distributions are provided as compressed `tar' archives
and have names of the form `mysql-VERSION.tar.gz', where VERSION is a
number like `4.0.22'.

You need the following tools to build and install MySQL from source:

   * GNU `gunzip' to uncompress the distribution.

   * A reasonable `tar' to unpack the distribution. GNU `tar' is known
     to work. Some operating systems come with a pre-installed version
     of `tar' that is known to have problems.  For example, Mac OS X
     `tar' and Sun `tar' are known to have problems with long
     filenames.  On Mac OS X, you can use the pre-installed `gnutar'
     program.  On other systems with a deficient `tar', you should
     install GNU `tar' first.

   * A working ANSI C++ compiler.  `gcc' 2.95.2 or later, `egcs' 1.0.2
     or later or `egcs 2.91.66', SGI C++, and SunPro C++ are some of the
     compilers that are known to work.  `libg++' is not needed when
     using `gcc'.  `gcc' 2.7.x has a bug that makes it impossible to
     compile some perfectly legal C++ files, such as `sql/sql_base.cc'.
     If you have only `gcc' 2.7.x, you must upgrade your `gcc' to be
     able to compile MySQL. `gcc' 2.8.1 is also known to have problems
     on some platforms, so it should be avoided if a new compiler
     exists for the platform.

     `gcc' 2.95.2 or later is recommended when compiling MySQL 3.23.x.

   * A good `make' program.  GNU `make' is always recommended and is
     sometimes required.  If you have problems, we recommend trying GNU
     `make' 3.75 or newer.

If you are using a version of `gcc' recent enough to understand the
`-fno-exceptions' option, it is _very important_ that you use this
option. Otherwise, you may compile a binary that crashes randomly. We
also recommend that you use `-felide-constructors' and `-fno-rtti' along
with `-fno-exceptions'. When in doubt, do the following:

     CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors \
            -fno-exceptions -fno-rtti" ./configure \
            --prefix=/usr/local/mysql --enable-assembler \
            --with-mysqld-ldflags=-all-static

On most systems, this will give you a fast and stable binary.

If you run into problems, _please always use `mysqlbug'_ when posting
questions to a MySQL mailing list.  Even if the problem isn't a bug,
`mysqlbug' gathers system information that will help others solve your
problem.  By not using `mysqlbug', you lessen the likelihood of getting
a solution to your problem.  You will find `mysqlbug' in the `scripts'
directory after you unpack the distribution.  *Note Bug reports::.

Source Installation Overview
----------------------------

The basic commands you must execute to install a MySQL source
distribution are:

     shell> groupadd mysql
     shell> useradd -g mysql mysql
     shell> gunzip < mysql-VERSION.tar.gz | tar -xvf -
     shell> cd mysql-VERSION
     shell> ./configure --prefix=/usr/local/mysql
     shell> make
     shell> make install
     shell> cp support-files/my-medium.cnf /etc/my.cnf
     shell> cd /usr/local/mysql
     shell> bin/mysql_install_db --user=mysql
     shell> chown -R root  .
     shell> chown -R mysql var
     shell> chgrp -R mysql .
     shell> bin/mysqld_safe --user=mysql &

For versions of MySQL older than 4.0, substitute `bin/safe_mysqld' for
`bin/mysqld_safe' in the final command.

If you start from a source RPM, do the following:

     shell> rpmbuild --rebuild --clean MySQL-VERSION.src.rpm

This will make a binary RPM that you can install. For older versions of
RPM, you may have to replace the command `rpmbuild' with `rpm' instead.

*Note*: This procedure does not set up any passwords for MySQL
accounts.  After following the procedure, proceed to *Note
Post-installation::, for post-installation setup and testing.

A more detailed version of the preceding description for installing
MySQL from a source distribution follows:

  1. Add a login user and group for `mysqld' to run as:

          shell> groupadd mysql
          shell> useradd -g mysql mysql

     These commands add the `mysql' group and the `mysql' user.  The
     syntax for `useradd' and `groupadd' may differ slightly on
     different versions of Unix.  They may also be called `adduser' and
     `addgroup'.

     You might want to call the user and group something else instead
     of `mysql'.  If so, substitute the appropriate name in the
     following steps.

  2. Pick the directory under which you want to unpack the
     distribution, and change location into it.

  3. Obtain a distribution file from one of the sites listed in *Note
     Getting MySQL: Getting MySQL.

  4. Unpack the distribution into the current directory:
          shell> gunzip < /PATH/TO/MYSQL-VERSION.tar.gz | tar xvf -

     This command creates a directory named `mysql-VERSION'.

     With GNU `tar', no separate invocation of `gunzip' is necessary.
     You can use the following alternative command to uncompress and
     extract the distribution:

          shell> tar zxvf /PATH/TO/MYSQL-VERSION-OS.tar.gz

  5. Change location into the top-level directory of the unpacked
     distribution:

          shell> cd mysql-VERSION

     Note that currently you must configure and build MySQL from this
     top-level directory.  You cannot build it in a different directory.

  6. Configure the release and compile everything:

          shell> ./configure --prefix=/usr/local/mysql
          shell> make

     When you run `configure', you might want to specify some options.
     Run `./configure --help' for a list of options.  *Note `configure'
     options: configure options, discusses some of the more useful
     options.

     If `configure' fails and you are going to send mail to a MySQL
     mailing list to ask for assistance, please include any lines from
     `config.log' that you think can help solve the problem.  Also
     include the last couple of lines of output from `configure'.  Post
     the bug report using the `mysqlbug' script.  *Note Bug reports::.

     If the compile fails, see *Note Compilation problems:: for help.

  7. Install the distribution:

          shell> make install

     If you want to set up an option file, use one of those present in
     the `support-files' directory as a template. For example:

          shell> cp support-files/my-medium.cnf /etc/my.cnf

     You might need to run these commands as `root'.

     If you want to configure support for `InnoDB' tables, you should
     edit the `/etc/my.cnf' file, remove the `#' character before the
     option lines that start with `innodb_...', and modify the option
     values to be what you want.  See *Note Option files:: and *Note
     `InnoDB' configuration: InnoDB configuration.

  8. Change location into the installation directory:

          shell> cd /usr/local/mysql

  9. If you haven't installed MySQL before, you must create the MySQL
     grant tables:

          shell> bin/mysql_install_db --user=mysql

     If you run the command as `root', you should use the `--user'
     option as shown.  The value of the option should be the name of
     the login account that you created in the first step to use for
     running the server.  If you run the command while logged in as
     that user, you can omit the `--user' option.

     Note that for MySQL versions older than 3.22.10,
     `mysql_install_db' left the server running after creating the grant
     tables.  This is no longer true; you will need to restart the
     server after performing the remaining steps in this procedure.

 10. Change the ownership of program binaries to `root' and ownership
     of the data directory to the user that you will run `mysqld' as.
     Assuming that you are located in the installation directory
     (`/usr/local/mysql'), the commands look like this:

          shell> chown -R root  .
          shell> chown -R mysql var
          shell> chgrp -R mysql .

     The first command changes the owner attribute of the files to the
     `root' user. The second changes the owner attribute of the data
     directory to the `mysql' user. The third changes the group
     attribute to the `mysql' group.

 11. If you would like MySQL to start automatically when you boot your
     machine, you can copy `support-files/mysql.server' to the location
     where your system has its startup files.  More information can be
     found in the `support-files/mysql.server' script itself and in
     *Note Automatic start::.

 12. You can set up new accounts using the `bin/mysql_setpermission'
     script if you install the `DBI' and `DBD::mysql' Perl modules.
     For instructions, see *Note Perl support::.


After everything has been installed, you should initialize and test your
distribution using this command:

     shell> /usr/local/mysql/bin/mysqld_safe --user=mysql &

For versions of MySQL older than 4.0, substitute `safe_mysqld' for
`mysqld_safe' in the command.

If that command fails immediately and prints `mysqld ended', you can
find some information in the `HOST_NAME.err' file in the data directory.

More information about `mysqld_safe' is given in *Note `mysqld_safe':
mysqld_safe.

*Note*: The accounts that are listed in the MySQL grant tables
initially have no passwords.  After starting the server, you should set
up passwords for them using the instructions in *Note
Post-installation::.

Typical `configure' Options
---------------------------

The `configure' script gives you a great deal of control over how you
configure a MySQL source distribution.  Typically you do this using
options on the `configure' command line.  You can also affect
`configure' using certain environment variables.  *Note Environment
variables::.  For a list of options supported by `configure', run this
command:

     shell> ./configure --help

Some of the more commonly used `configure' options are described here:

   * To compile just the MySQL client libraries and client programs and
     not the server, use the `--without-server' option:

          shell> ./configure --without-server

     If you don't have a C++ compiler, `mysql' will not compile (it is
     the one client program that requires C++).  In this case, you can
     remove the code in `configure' that tests for the C++ compiler and
     then run `./configure' with the `--without-server' option. The
     compile step will still try to build `mysql', but you can ignore
     any warnings about `mysql.cc'.  (If `make' stops, try `make -k' to
     tell it to continue with the rest of the build even if errors
     occur.)

   * If you want to build the embedded MySQL library (`libmysqld.a')
     you should use the `--with-embedded-server' option.

   * If you don't want your log files and database directories located
     under `/usr/local/var', use a `configure' command something like
     one of these:

          shell> ./configure --prefix=/usr/local/mysql
          shell> ./configure --prefix=/usr/local \
                     --localstatedir=/usr/local/mysql/data

     The first command changes the installation prefix so that
     everything is installed under `/usr/local/mysql' rather than the
     default of `/usr/local'.  The second command preserves the default
     installation prefix, but overrides the default location for
     database directories (normally `/usr/local/var') and changes it to
     `/usr/local/mysql/data'.  After you have compiled MySQL, you can
     change these options with option files. *Note Option files::.

   * If you are using Unix and you want the MySQL socket located
     somewhere other than the default location (normally in the
     directory `/tmp' or `/var/run'), use a `configure' command like
     this:

          shell> ./configure \
                     --with-unix-socket-path=/usr/local/mysql/tmp/mysql.sock

     The socket filename must be an absolute pathname.  You can also
     change the location of `mysql.sock' later by using a MySQL option
     file. *Note Problems with `mysql.sock': Problems with mysql.sock.

   * If you want to compile statically linked programs (for example, to
     make a binary distribution, to get more speed, or to work around
     problems with some Red Hat Linux distributions), run `configure'
     like this:

          shell> ./configure --with-client-ldflags=-all-static \
                     --with-mysqld-ldflags=-all-static

   * If you are using `gcc' and don't have `libg++' or `libstdc++'
     installed, you can tell `configure' to use `gcc' as your C++
     compiler:

          shell> CC=gcc CXX=gcc ./configure

     When you use `gcc' as your C++ compiler, it will not attempt to
     link in `libg++' or `libstdc++'.  This may be a good idea to do
     even if you have these libraries installed, because some versions
     of them have caused strange problems for MySQL users in the past.

     The following list indicates some compilers and environment
     variable settings that are commonly used with each one.

    `gcc' 2.7.2:
               CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors"

    `egcs' 1.0.3a:
               CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors \
               -fno-exceptions -fno-rtti"

    `gcc' 2.95.2:
               CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
               -felide-constructors -fno-exceptions -fno-rtti"

    `pgcc' 2.90.29 or newer:
               CFLAGS="-O3 -mpentiumpro -mstack-align-double" CXX=gcc \
               CXXFLAGS="-O3 -mpentiumpro -mstack-align-double \
               -felide-constructors -fno-exceptions -fno-rtti"

     In most cases, you can get a reasonably optimized MySQL binary by
     using the options from the preceding list and adding the following
     options to the `configure' line:

          --prefix=/usr/local/mysql --enable-assembler \
          --with-mysqld-ldflags=-all-static

     The full `configure' line would, in other words, be something like
     the following for all recent `gcc' versions:

          CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
          -felide-constructors -fno-exceptions -fno-rtti" ./configure \
          --prefix=/usr/local/mysql --enable-assembler \
          --with-mysqld-ldflags=-all-static

     The binaries we provide on the MySQL Web site at
     `http://www.mysql.com/' are all compiled with full optimization and
     should be perfect for most users.  *Note MySQL binaries::.  There
     are some configuration settings you can tweak to make an even
     faster binary, but these are only for advanced users.  *Note
     Compile and link options::.

     If the build fails and produces errors about your compiler or
     linker not being able to create the shared library
     `libmysqlclient.so.#' (where `#' is a version number), you can
     work around this problem by giving the `--disable-shared' option
     to `configure'.  In this case, `configure' will not build a shared
     `libmysqlclient.so.#' library.

   * By default, MySQL uses the `latin1' (ISO-8859-1) character set. To
     change the default set, use the `--with-charset' option:
          shell> ./configure --with-charset=CHARSET
     CHARSET may be one of `big5', `cp1251', `cp1257', `czech',
     `danish', `dec8', `dos', `euc_kr', `gb2312', `gbk', `german1',
     `hebrew', `hp8', `hungarian', `koi8_ru', `koi8_ukr', `latin1',
     `latin2', `sjis', `swe7', `tis620', `ujis', `usa7', or
     `win1251ukr'.  *Note Character sets::.

     As of MySQL 4.1.1, the default collation may also be specified.
     MySQL uses the `latin1_swedish_ci' collation. To change this, use
     the `--with-collation' option:

          shell> ./configure --with-collation=COLLATION

     To change both the character set and the collation, use both the
     `--with-charset' and `--with-collation' options.  The collation
     must be a legal collation for the character set.  (Use the `SHOW
     COLLATION' statement to determine which collations are available
     for each character set.)

     If you want to convert characters between the server and the
     client, you should take a look at the `SET CHARACTER SET'
     statement.  *Note `SET': SET OPTION.

     *Warning:* If you change character sets after having created any
     tables, you will have to run `myisamchk -r -q
     --set-character-set=CHARSET' on every table. Your indexes may be
     sorted incorrectly otherwise.  (This can happen if you install
     MySQL, create some tables, then reconfigure MySQL to use a
     different character set and reinstall it.)

     With the `configure' option `--with-extra-charsets=LIST', you can
     define which additional character sets should be compiled into the
     server.  LIST is either a list of character set names separated by
     spaces, `complex' to include all character sets that can't be
     dynamically loaded, or `all' to include all character sets into
     the binaries.

   * To configure MySQL with debugging code, use the `--with-debug'
     option:
          shell> ./configure --with-debug
     This causes a safe memory allocator to be included that can find
     some errors and that provides output about what is happening.
     *Note Debugging server::.

   * If your client programs are using threads, you also must compile a
     thread-safe version of the MySQL client library with the
     `--enable-thread-safe-client' configure option. This will create a
     `libmysqlclient_r' library with which you should link your threaded
     applications.  *Note Threaded clients::.

   * Options that pertain to particular systems can be found in the
     system-specific section of this manual.  *Note Operating System
     Specific Notes::.

Installing from the Development Source Tree
-------------------------------------------

*Caution*: You should read this section only if you are interested in
helping us test our new code. If you just want to get MySQL up and
running on your system, you should use a standard release distribution
(either a binary or source distribution will do).

To obtain our most recent development source tree, use these
instructions:

  1. Download BitKeeper from
     `http://www.bitmover.com/cgi-bin/download.cgi'.  You will need
     Bitkeeper 3.0 or newer to access our repository.

  2. Follow the instructions to install it.

  3. After BitKeeper has been installed, first go to the directory you
     want to work from, and then use one of the following commands to
     clone the MySQL version branch of your choice:

     To clone the old 3.23 branch, use this command:

          shell> bk clone bk://mysql.bkbits.net/mysql-3.23 mysql-3.23

     To clone the 4.0 stable (production) branch, use this command:

          shell> bk clone bk://mysql.bkbits.net/mysql-4.0 mysql-4.0

     To clone the 4.1 gamma branch, use this command:

          shell> bk clone bk://mysql.bkbits.net/mysql-4.1 mysql-4.1

     To clone the 5.0 development branch, use this command:

          shell> bk clone bk://mysql.bkbits.net/mysql-5.0 mysql-5.0

     In the preceding examples, the source tree will be set up in the
     `mysql-3.23/', `mysql-4.0/', `mysql-4.1/', or `mysql-5.0/'
     subdirectory of your current directory.

     If you are behind a firewall and can only initiate HTTP
     connections, you can also use BitKeeper via HTTP.

     If you are required to use a proxy server, set the environment
     variable `http_proxy' to point to your proxy:

          shell> export http_proxy="http://your.proxy.server:8080/"

     Now, simply replace the `bk://' with `http://' when doing a clone.
     Example:

          shell> bk clone http://mysql.bkbits.net/mysql-4.1 mysql-4.1

     The initial download of the source tree may take a while,
     depending on the speed of your connection. Please be patient.

  4. You will need GNU `make', `autoconf' 2.53 (or newer), `automake'
     1.5, `libtool' 1.5, and `m4' to run the next set of commands. Even
     though many operating systems already come with their own
     implementation of `make', chances are high that the compilation
     will fail with strange error messages. Therefore, it is highly
     recommended that you use GNU `make' (sometimes named `gmake')
     instead.

     Fortunately, a large number of operating systems already ship with
     the GNU toolchain preinstalled or supply installable packages of
     these. In any case, they can also be downloaded from the following
     locations:

        * `http://www.gnu.org/software/autoconf/'

        * `http://www.gnu.org/software/automake/'

        * `http://www.gnu.org/software/libtool/'

        * `http://www.gnu.org/software/m4/'

        * `http://www.gnu.org/software/make/'

     If you are trying to configure MySQL 4.1 or later, you will also
     need GNU `bison' 1.75 or later.  Older versions of `bison' may
     report this error:

          sql_yacc.yy:#####: fatal error: maximum table size (32767) exceeded

     Note: The maximum table size is not actually exceeded; the error
     is caused by bugs in older versions of `bison'.

     Versions of MySQL before version 4.1 may also compile with other
     `yacc' implementations (for example, BSD `yacc' 91.7.30). For later
     versions, GNU `bison' is required.

     The following example shows the typical commands required to
     configure a source tree. The first `cd' command changes location
     into the top-level directory of the tree; replace `mysql-4.0' with
     the appropriate directory name.

          shell> cd mysql-4.0
          shell> bk -r edit
          shell> aclocal; autoheader; autoconf; automake
          shell> (cd innobase; aclocal; autoheader; autoconf; automake)
          shell> (cd bdb/dist; sh s_all)
          shell> ./configure  # Add your favorite options here
          make

     The command lines that change directory into the `innobase' and
     `bdb/dist' directories are used to configure the `InnoDB' and
     Berkeley DB (`BDB') storage engines.  You can omit these command
     lines if you to not require `InnoDB' or `BDB' support.

     If you get some strange errors during this stage, verify that you
     really have `libtool' installed.

     A collection of our standard configuration scripts is located in
     the `BUILD/' subdirectory.  You may find it more convenient to use
     the `BUILD/compile-pentium-debug' script than the preceding set of
     shell commands. To compile on a different architecture, modify the
     script by removing flags that are Pentium-specific.

  5. When the build is done, run `make install'.  Be careful with this
     on a production machine; the command may overwrite your live
     release installation.  If you have another installation of MySQL,
     we recommend that you run `./configure' with different values for
     the `--prefix', `--with-tcp-port', and `--unix-socket-path' options
     than those used for your production server.

  6. Play hard with your new installation and try to make the new
     features crash.  Start by running `make test'.  *Note MySQL test
     suite::.

  7. If you have gotten to the `make' stage and the distribution does
     not compile, please report it in our bugs database at
     `http://bugs.mysql.com/'.  If you have installed the latest
     versions of the required GNU tools, and they crash trying to
     process our configuration files, please report that also.
     However, if you execute `aclocal' and get a `command not found'
     error or a similar problem, do not report it.  Instead, make sure
     that all the necessary tools are installed and that your `PATH'
     variable is set correctly so that your shell can find them.

  8. After the initial `bk clone' operation to obtain the source tree,
     you should run `bk pull' periodically to get updates.

  9. You can examine the change history for the tree with all the diffs
     by using `bk revtool'.  If you see some funny diffs or code that
     you have a question about, do not hesitate to send email to the
     MySQL `internals' mailing list.  *Note Mailing-list::.  Also, if
     you think you have a better idea on how to do something, send an
     email message to the same address with a patch.  `bk diffs' will
     produce a patch for you after you have made changes to the source.
     If you do not have the time to code your idea, just send a
     description.

 10. BitKeeper has a nice help utility that you can access via `bk
     helptool'.

 11. Please note that any commits (made via `bk ci' or `bk citool') will
     trigger the posting of a message with the changeset to our
     internals mailing list, as well as the usual openlogging.org
     submission with just the changeset comments.  Generally, you
     wouldn't need to use commit (since the public tree will not allow
     `bk push'), but rather use the `bk diffs' method described
     previously.


You can also browse changesets, comments, and source code online. For
example, to browse this information for MySQL 4.1, go to
`http://mysql.bkbits.net:8080/mysql-4.1'.

The manual is in a separate tree that can be cloned with:

     shell> bk clone bk://mysql.bkbits.net/mysqldoc mysqldoc

There are also public BitKeeper trees for MySQL Control Center and
MyODBC. They can be cloned respectively as follows.

To clone MySQL Control center, use this command:

     shell> bk clone http://mysql.bkbits.net/mysqlcc mysqlcc

To clone MyODBC, use this command:

     shell> bk clone http://mysql.bkbits.net/myodbc3 myodbc3

To clone Connector/NET, use this command:

     shell> bk clone http://mysql.bkbits.net/connector-net connector-net

Dealing with Problems Compiling MySQL
-------------------------------------

All MySQL programs compile cleanly for us with no warnings on Solaris
or Linux using `gcc'.  On other systems, warnings may occur due to
differences in system include files.  See *Note MIT-pthreads:: for
warnings that may occur when using MIT-pthreads.  For other problems,
check the following list.

The solution to many problems involves reconfiguring.  If you do need to
reconfigure, take note of the following:

   * If `configure' is run after it already has been run, it may use
     information that was gathered during its previous invocation.  This
     information is stored in `config.cache'.  When `configure' starts
     up, it looks for that file and reads its contents if it exists, on
     the assumption that the information is still correct.  That
     assumption is invalid when you reconfigure.

   * Each time you run `configure', you must run `make' again to
     recompile.  However, you may want to remove old object files from
     previous builds first because they were compiled using different
     configuration options.

To prevent old configuration information or object files from being
used, run these commands before re-running `configure':

     shell> rm config.cache
     shell> make clean

Alternatively, you can run `make distclean'.

The following list describes some of the problems when compiling MySQL
that have been found to occur most often:

   * If you get errors such as the ones shown here when compiling
     `sql_yacc.cc', you probably have run out of memory or swap space:

          Internal compiler error: program cc1plus got fatal signal 11
          Out of virtual memory
          Virtual memory exhausted

     The problem is that `gcc' requires a huge amount of memory to
     compile `sql_yacc.cc' with inline functions.  Try running
     `configure' with the `--with-low-memory' option:

          shell> ./configure --with-low-memory

     This option causes `-fno-inline' to be added to the compile line
     if you are using `gcc' and `-O0' if you are using something else.
     You should try the `--with-low-memory' option even if you have so
     much memory and swap space that you think you can't possibly have
     run out.  This problem has been observed to occur even on systems
     with generous hardware configurations and the `--with-low-memory'
     option usually fixes it.

   * By default, `configure' picks `c++' as the compiler name and GNU
     `c++' links with `-lg++'.  If you are using `gcc', that behavior
     can cause problems during configuration such as this:

          configure: error: installation or configuration problem:
          C++ compiler cannot create executables.

     You might also observe problems during compilation related to
     `g++', `libg++', or `libstdc++'.

     One cause of these problems is that you may not have `g++', or you
     may have `g++' but not `libg++', or `libstdc++'.  Take a look at
     the `config.log' file.  It should contain the exact reason why
     your C++ compiler didn't work.  To work around these problems, you
     can use `gcc' as your C++ compiler.  Try setting the environment
     variable `CXX' to `"gcc -O3"'.  For example:

          shell> CXX="gcc -O3" ./configure

     This works because `gcc' compiles C++ sources as well as `g++'
     does, but does not link in `libg++' or `libstdc++' by default.

     Another way to fix these problems is to install `g++', `libg++',
     and `libstdc++'.  We would, however, like to recommend that you
     not use `libg++' or `libstdc++' with MySQL because this will only
     increase the binary size of `mysqld' without giving you any
     benefits.  Some versions of these libraries have also caused
     strange problems for MySQL users in the past.

     Using `gcc' as the C++ compiler is also required if you want to
     compile MySQL with RAID functionality (see *Note CREATE TABLE::
     for more info on RAID table type) and you are using GNU `gcc'
     version 3 and above. If you get errors like those following during
     the linking stage when you configure MySQL to compile with the
     option `--with-raid', try to use `gcc' as your C++ compiler by
     defining the `CXX' environment variable:

          gcc -O3 -DDBUG_OFF -rdynamic -o isamchk isamchk.o sort.o  libnisam.a
          ../mysys/libmysys.a ../dbug/libdbug.a ../strings/libmystrings.a
           -lpthread -lz -lcrypt -lnsl -lm -lpthread
          ../mysys/libmysys.a(raid.o)(.text+0x79): In function
          `my_raid_create':: undefined reference to `operator new(unsigned)'
          ../mysys/libmysys.a(raid.o)(.text+0xdd): In function
          `my_raid_create':: undefined reference to `operator delete(void*)'
          ../mysys/libmysys.a(raid.o)(.text+0x129): In function
          `my_raid_open':: undefined reference to `operator new(unsigned)'
          ../mysys/libmysys.a(raid.o)(.text+0x189): In function
          `my_raid_open':: undefined reference to `operator delete(void*)'
          ../mysys/libmysys.a(raid.o)(.text+0x64b): In function
          `my_raid_close':: undefined reference to `operator delete(void*)'
          collect2: ld returned 1 exit status

   * If your compile fails with errors such as any of the following,
     you must upgrade your version of `make' to GNU `make':

          making all in mit-pthreads
          make: Fatal error in reader: Makefile, line 18:
          Badly formed macro assignment
     Or:
          make: file `Makefile' line 18: Must be a separator (:
     Or:
          pthread.h: No such file or directory

     Solaris and FreeBSD are known to have troublesome `make' programs.

     GNU `make' Version 3.75 is known to work.

   * If you want to define flags to be used by your C or C++ compilers,
     do so by adding the flags to the `CFLAGS' and `CXXFLAGS'
     environment variables.  You can also specify the compiler names
     this way using `CC' and `CXX'.  For example:

          shell> CC=gcc
          shell> CFLAGS=-O3
          shell> CXX=gcc
          shell> CXXFLAGS=-O3
          shell> export CC CFLAGS CXX CXXFLAGS

     See *Note MySQL binaries::, for a list of flag definitions that
     have been found to be useful on various systems.

   * If you get an error message like this, you need to upgrade your
     `gcc' compiler:

          client/libmysql.c:273: parse error before `__attribute__'

     `gcc' 2.8.1 is known to work, but we recommend using `gcc' 2.95.2
     or `egcs' 1.0.3a instead.

   * If you get errors such as those shown here when compiling `mysqld',
     `configure' didn't correctly detect the type of the last argument
     to `accept()', `getsockname()', or `getpeername()':

          cxx: Error: mysqld.cc, line 645: In this statement, the referenced
               type of the pointer value ''length'' is ''unsigned long'',
               which is not compatible with ''int''.
          new_sock = accept(sock, (struct sockaddr *)&cAddr, &length);

     To fix this, edit the `config.h' file (which is generated by
     `configure').  Look for these lines:

          /* Define as the base type of the last arg to accept */
          #define SOCKET_SIZE_TYPE XXX

     Change `XXX' to `size_t' or `int', depending on your operating
     system.  (Note that you will have to do this each time you run
     `configure' because `configure' regenerates `config.h'.)

   * The `sql_yacc.cc' file is generated from `sql_yacc.yy'.  Normally
     the build process doesn't need to create `sql_yacc.cc', because
     MySQL comes with an already generated copy.  However, if you do
     need to re-create it, you might encounter this error:

          "sql_yacc.yy", line XXX fatal: default action causes potential...

     This is a sign that your version of `yacc' is deficient.  You
     probably need to install `bison' (the GNU version of `yacc') and
     use that instead.

   * On Debian Linux 3.0, you need to install `gawk' instead of the
     default `mawk' if you want to compile MySQL 4.1 or higher with
     Berkeley DB support.

   * If you need to debug `mysqld' or a MySQL client, run `configure'
     with the `--with-debug' option, then recompile and link your
     clients with the new client library.  *Note Debugging client::.

   * If you get a compilation error on Linux (for example, SuSE Linux
     8.1 or Red Hat Linux 7.3) similar to the following one:

          libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from
          incompatible pointer type
          libmysql.c:1329: too few arguments to function `gethostbyname_r'
          libmysql.c:1329: warning: assignment makes pointer from integer
          without a cast
          make[2]: *** [libmysql.lo] Error 1

     By default, the `configure' script attempts to determine the
     correct number of arguments by using `g++' the GNU C++ compiler.
     This test yields wrong results if `g++' is not installed. There
     are two ways to work around this problem:

        * Make sure that the GNU C++ `g++' is installed. On some Linux
          distributions, the required package is called `gpp'; on
          others, it is named `gcc-c++'.

        * Use `gcc' as your C++ compiler by setting the `CXX'
          environment variable to `gcc':
               export CXX="gcc"

     Please note that you need to run `configure' again afterward.


MIT-pthreads Notes
------------------

This section describes some of the issues involved in using
MIT-pthreads.

On Linux, you should _not_ use MIT-pthreads. Use the installed
LinuxThreads implementation instead.  *Note Linux::.

If your system does not provide native thread support, you will need to
build MySQL using the MIT-pthreads package.  This includes older
FreeBSD systems, SunOS 4.x, Solaris 2.4 and earlier, and some others.
*Note Which OS::.

Beginning with MySQL 4.0.2, MIT-pthreads is no longer part of the
source distribution. If you require this package, you need to download
it separately from
`http://www.mysql.com/Downloads/Contrib/pthreads-1_60_beta6-mysql.tar.gz'

After downloading, extract this source archive into the top level of the
MySQL source directory. It will create a new subdirectory named
`mit-pthreads'.

   * On most systems, you can force MIT-pthreads to be used by running
     `configure' with the `--with-mit-threads' option:

          shell> ./configure --with-mit-threads

     Building in a non-source directory is not supported when using
     MIT-pthreads because we want to minimize our changes to this code.

   * The checks that determine whether to use MIT-pthreads occur only
     during the part of the configuration process that deals with the
     server code.  If you have configured the distribution using
     `--without-server' to build only the client code, clients will not
     know whether MIT-pthreads is being used and will use Unix socket
     connections by default.  Because Unix socket files do not work
     under MIT-pthreads on some platforms, this means you will need to
     use `-h' or `--host' when you run client programs.

   * When MySQL is compiled using MIT-pthreads, system locking is
     disabled by default for performance reasons.  You can tell the
     server to use system locking with the `--external-locking' option.
     This is needed only if you want to be able to run two MySQL
     servers against the same data files, which is not recommended.

   * Sometimes the pthread `bind()' command fails to bind to a socket
     without any error message (at least on Solaris).  The result is
     that all connections to the server fail.  For example:

          shell> mysqladmin version
          mysqladmin: connect to server at '' failed;
          error: 'Can't connect to mysql server on localhost (146)'

     The solution to this is to kill the `mysqld' server and restart it.
     This has only happened to us when we have forced down the server
     and done a restart immediately.

   * With MIT-pthreads, the `sleep()' system call isn't interruptible
     with `SIGINT' (break).  This is only noticeable when you run
     `mysqladmin --sleep'.  You must wait for the `sleep()' call to
     terminate before the interrupt is served and the process stops.

   * When linking, you may receive warning messages like these (at
     least on Solaris); they can be ignored:

          ld: warning: symbol `_iob' has differing sizes:
              (file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
          file /usr/lib/libc.so value=0x140);
              /my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
          ld: warning: symbol `__iob' has differing sizes:
              (file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
          file /usr/lib/libc.so value=0x140);
              /my/local/pthreads/lib/libpthread.a(findfp.o) definition taken

   * Some other warnings also can be ignored:

          implicit declaration of function `int strtoll(...)'
          implicit declaration of function `int strtoul(...)'

   * We haven't gotten `readline' to work with MIT-pthreads.  (This
     isn't needed, but may be interesting for someone.)

Installing MySQL from Source on Windows
---------------------------------------

These instructions describe how to build MySQL binaries from source for
versions 4.1 and above on Windows. Instructions are provided for
building binaries from a standard source distribution or from the
BitKeeper tree that contains the latest development source.

*Note*: The instructions in this document are strictly for users who
want to test MySQL on Windows from the latest source distribution or
from the BitKeeper tree.  For production use, MySQL AB does not advise
using a MySQL server built by yourself from source.  Normally, it is
best to use precompiled binary distributions of MySQL that are built
specifically for optimal performance on Windows by MySQL AB.
Instructions for installing a binary distributions are available at
*Note Windows installation::.

To build MySQL on Windows from source, you need the following compiler
and resources available on your Windows system:

   * VC++ 6.0 compiler (updated with 4 or 5 SP and pre-processor
     package).  The pre-processor package is necessary for the macro
     assembler.  More details can be found at
     `http://msdn.microsoft.com/vstudio/downloads/updates/sp/vs6/sp5/faq.aspx'.

   * Approximately 45MB disk space.

   * 64MB RAM.


You'll also need a MySQL source distribution for Windows.  There are
two ways you can get a source distribution for MySQL version 4.1 and
above:

  1. Obtain a source distribution packaged by MySQL AB for the
     particular version of MySQL in which you are interested.
     Prepackaged source distributions are available for released
     versions of MySQL and can be obtained from
     `http://dev.mysql.com/downloads/'.

  2. You can package a source distribution yourself from the latest
     BitKeeper developer source tree. If you plan to do this, you must
     create the package on a Unix system and then transfer it to your
     Windows system.  (The reason for this is that some of the
     configuration and build steps require tools that work only on
     Unix.)  The BitKeeper approach thus requires:

        * A system running Unix, or a Unix-like system such as Linux.

        * BitKeeper 3.0 installed on that system. You can obtain
          BitKeeper from `http://www.bitkeeper.com/'.



If you are using a Windows source distribution, you can go directly to
*Note Windows VC++ Build::. To build from the BitKeeper tree, proceed to
*Note Windows BitKeeper Build::.

If you find something not working as expected, or you have suggestions
about ways to improve the current build process on Windows, please send
a message to the `win32' mailing list.  *Note Mailing-list::.

Building MySQL Using VC++
.........................

*Note*: VC++ workspace files for MySQL 4.1 and above are compatible with
Microsoft Visual Studio 6.0 and above (7.0/.NET) editions and tested by
MySQL AB staff before each release.

Follow this procedure to build MySQL:

  1. Create a work directory (for example, `C:\workdir').

  2. Unpack the source distribution in the aforementioned directory
     using `WinZip' or other Windows tool that can read `.zip' files.

  3. Start the VC++ 6.0 compiler.

  4. In the `File' menu, select `Open Workspace'.

  5. Open the `mysql.dsw' workspace you find in the work directory.

  6. From the `Build' menu, select the `Set Active Configuration' menu.

  7. Click over the screen selecting `mysqld - Win32 Debug' and click
     OK.

  8. Press `F7' to begin the build of the debug server, libraries, and
     some client applications.

  9. Compile the release versions that you want in the same way.

 10. Debug versions of the programs and libraries are placed in the
     `client_debug' and `lib_debug' directories.  Release versions of
     the programs and libraries are placed in the `client_release' and
     `lib_release' directories.  Note that if you want to build both
     debug and release versions, you can select the `Build All' option
     from the `Build' menu.

 11. Test the server.  The server built using the preceding instructions
     will expect that the MySQL base directory and data directory are
     `C:\mysql' and `C:\mysql\data' by default. If you want to test
     your server using the source tree root directory and its data
     directory as the base directory and data directory, you will need
     to tell the server their pathnames. You can either do this on the
     command line with the `--basedir' and `--datadir' options, or
     place appropriate options in an option file (the `my.ini' file in
     your Windows directory or `C:\my.cnf').  If you have an existing
     data directory elsewhere that you want to use, you can specify its
     pathname instead.

 12. Start your server from the `client_release' or `client_debug'
     directory, depending on which server you want to use. The general
     server startup instructions are at *Note Windows installation::.
     You'll need to adapt the instructions appropriately if you want to
     use a different base directory or data directory.

 13. When the server is running in standalone fashion or as a service
     based on your configuration, try to connect to it from the `mysql'
     interactive command-line utility that exists in your
     `client_release' or `client_debug' directory.


When you are satisfied that the programs you have built are working
correctly, stop the server. Then install MySQL as follows:

  1. Create the directories where you want to install MySQL.  For
     example, to install into `C:\mysql', use these commands:

          C:\> mkdir C:\mysql
          C:\> mkdir C:\mysql\bin
          C:\> mkdir C:\mysql\data
          C:\> mkdir C:\mysql\share
          C:\> mkdir C:\mysql\scripts

     If you want to compile other clients and link them to MySQL, you
     should also create several additional directories:

          C:\> mkdir C:\mysql\include
          C:\> mkdir C:\mysql\lib
          C:\> mkdir C:\mysql\lib\debug
          C:\> mkdir C:\mysql\lib\opt

     If you want to benchmark MySQL, create this directory:

          C:\> mkdir C:\mysql\sql-bench

     Benchmarking requires Perl support.

  2. From the `workdir' directory, copy into the `C:\mysql' directory
     the following directories:

          C:\> cd \workdir
          C:\workdir> copy client_release\*.exe C:\mysql\bin
          C:\workdir> copy client_debug\mysqld.exe C:\mysql\bin\mysqld-debug.exe
          C:\workdir> xcopy scripts\*.* C:\mysql\scripts /E
          C:\workdir> xcopy share\*.* C:\mysql\share /E

     If you want to compile other clients and link them to MySQL, you
     should also copy several libraries and header files:

          C:\workdir> copy lib_debug\mysqlclient.lib C:\mysql\lib\debug
          C:\workdir> copy lib_debug\libmysql.* C:\mysql\lib\debug
          C:\workdir> copy lib_debug\zlib.* C:\mysql\lib\debug
          C:\workdir> copy lib_release\mysqlclient.lib C:\mysql\lib\opt
          C:\workdir> copy lib_release\libmysql.* C:\mysql\lib\opt
          C:\workdir> copy lib_release\zlib.* C:\mysql\lib\opt
          C:\workdir> copy include\*.h C:\mysql\include
          C:\workdir> copy libmysql\libmysql.def C:\mysql\include

     If you want to benchmark MySQL, you should also do this:

          C:\workdir> xcopy sql-bench\*.* C:\mysql\bench /E


Set up and start the server in the same way as for the binary Windows
distribution.  *Note Windows installation::.

Creating a Windows Source Package from the Latest Development Source
....................................................................

To create a Windows source package from the current BitKeeper source
tree, use the following instructions. Please note that this procedure
must be performed on a system running a Unix or Unix-like operating
system.  For example, the procedure is known to work well on Linux.

  1. Clone the BitKeeper source tree for MySQL (version 4.1 or above,
     as desired).  For more information on how to clone the source tree,
     see the instructions at *Note Installing source tree::.

  2. Configure and build the distribution so that you have a server
     binary to work with.  One way to do this is to run the following
     command in the top-level directory of your source tree:

          shell> ./BUILD/compile-pentium-max

  3. After making sure that the build process completed successfully,
     run the following utility script from top-level directory of your
     source tree:

          shell> ./scripts/make_win_src_distribution

     This script creates a Windows source package to be used on your
     Windows system.  You can supply different options to the script
     based on your needs. It accepts the following options:

    `--help'
          Display a help message.

    `--debug'
          Print information about script operations, do not create
          package.

    `--tmp'
          Specify the temporary location.

    `--suffix'
          Suffix name for the package.

    `--dirname'
          Directory name to copy files (intermediate).

    `--silent'
          Do not print verbose list of files processed.

    `--tar'
          Create `tar.gz' package instead of `.zip' package.

     By default, `make_win_src_distribution' creates a Zip-format
     archive with the name `mysql-VERSION-win-src.zip', where VERSION
     represents the version of your MySQL source tree.

  4. Copy or upload to your Windows machine the Windows source package
     that you have just created. To compile it, use the instructions in
     *Note Windows VC++ Build::.


Compiling MySQL Clients on Windows
----------------------------------

In your source files, you should include `my_global.h' before `mysql.h':

     #include <my_global.h>
     #include <mysql.h>

`my_global.h' includes any other files needed for Windows compatibility
(such as `windows.h') if you compile your program on Windows.

You can either link your code with the dynamic `libmysql.lib' library,
which is just a wrapper to load in `libmysql.dll' on demand, or link
with the static `mysqlclient.lib' library.

The MySQL client libraries are compiled as threaded libraries, so you
should also compile your code to be multi-threaded.

Post-Installation Setup and Testing
===================================

After installing MySQL, there are some issues you should address.  For
example, on Unix, you should initialize the data directory and create
the MySQL grant tables.  On all platforms, an important security
concern is that the initial accounts in the grant tables have no
passwords.  You should assign passwords to prevent unauthorized access
to the MySQL server.  For MySQL 4.1.3 and up, you can create time zone
tables to enable recognition of named time zones. (Currently, these
tables can be populated only on Unix. This problem will be addressed
soon for Windows.)

The following sections include post-installation procedures that are
specific to Windows systems and to Unix systems. Another section, *Note
Starting server::, applies to all platforms; it describes what to do if
you have trouble getting the server to start.  *Note Default
privileges:: also applies to all platforms. You should follow its
instructions to make sure that you have properly protected your MySQL
accounts by assigning passwords to them.

When you are ready to create additional user accounts, you can find
information on the MySQL access control system and account management in
*Note Privilege system:: and *Note User Account Management::.

Windows Post-Installation Procedures
------------------------------------

On Windows, the data directory and the grant tables do not have to be
created. MySQL Windows distributions include the grant tables already
set up with a set of preinitialized accounts in the `mysql' database
under the data directory. You do not run the `mysql_install_db' script
that is used on Unix.  However, you should assign passwords to the
accounts.  The procedure for this is given in *Note Default
privileges::.

Before setting up passwords, you might want to try running some client
programs to make sure that you can connect to the server and that it is
operating properly.  Make sure the server is running (*note Windows
server first start::), then issue the following commands to verify that
you can retrieve information from the server.  The output should be
similar to what is shown here:

     C:\> C:\mysql\bin\mysqlshow
     +-----------+
     | Databases |
     +-----------+
     | mysql     |
     | test      |
     +-----------+

     C:\> C:\mysql\bin\mysqlshow mysql
     Database: mysql
     +--------------+
     |    Tables    |
     +--------------+
     | columns_priv |
     | db           |
     | func         |
     | host         |
     | tables_priv  |
     | user         |
     +--------------+

     C:\> C:\mysql\bin\mysql -e "SELECT Host,Db,User FROM db" mysql
     +------+-------+------+
     | host | db    | user |
     +------+-------+------+
     | %    | test% |      |
     +------+-------+------+

If you are running a version of Windows that supports services and you
want the MySQL server to run automatically when Windows starts, see
*Note NT start::.

Unix Post-Installation Procedures
---------------------------------

After installing MySQL on Unix, you need to initialize the grant tables,
start the server, and make sure that the server works okay.  You may
also wish to arrange for the server to be started and stopped
automatically when your system starts and stops.  You should also
assign passwords to the accounts in the grant tables.

On Unix, the grant tables are set up by the `mysql_install_db' program.
For some installation methods, this program is run for you
automatically:

   * If you install MySQL on Linux using RPM distributions, the server
     RPM runs `mysql_install_db'.

   * If you install MySQL on Mac OS X using a PKG distribution, the
     installer runs `mysql_install_db'.

Otherwise, you'll need to run `mysql_install_db' yourself.

The following procedure describes how to initialize the grant tables (if
that has not already been done) and then start the server. It also
suggests some commands that you can use to test whether the server is
accessible and working properly.  For information about starting and
stopping the server automatically, see *Note Automatic start::.

After you complete the procedure and have the server running, you should
assign passwords to the accounts created by `mysql_install_db'.
Instructions for doing so are given in *Note Default privileges::.

In the examples shown here, the server runs under the user ID of the
`mysql' login account. This assumes that such an account exists.
Either create the account if it does not exist, or substitute the name
of a different existing login account that you plan to use for running
the server.

  1. Change location into the top-level directory of your MySQL
     installation, represented here by BASEDIR:

          shell> cd BASEDIR

     BASEDIR is likely to be something like `/usr/local/mysql' or
     `/usr/local'.  The following steps assume that you are located in
     this directory.

  2. If necessary, run the `mysql_install_db' program to set up the
     initial MySQL grant tables containing the privileges that
     determine how users are allowed to connect to the server. You'll
     need to do this if you used a distribution type that doesn't run
     the program for you.

     Typically, `mysql_install_db' needs to be run only the first time
     you install MySQL, so you can skip this step if you are upgrading
     an existing installation, However, `mysql_install_db' does not
     overwrite any existing privilege tables, so it should be safe to
     run in any circumstances.

     To initialize the grant tables, use one of the following commands,
     depending on whether `mysql_install_db' is located in the `bin' or
     `scripts' directory:

          shell> bin/mysql_install_db --user=mysql
          shell> scripts/mysql_install_db --user=mysql

     The `mysql_install_db' script creates the data directory, the
     `mysql' database that holds all database privileges, and the `test'
     database that you can use to test MySQL. The script also creates
     privilege table entries for `root' accounts and anonymous-user
     accounts.  The accounts have no passwords initially.  A
     description of their initial privileges is given in *Note Default
     privileges::.  Briefly, these privileges allow the MySQL `root'
     user to do anything, and allow anybody to create or use databases
     with a name of `test' or starting with `test_'.

     It is important to make sure that the database directories and
     files are owned by the `mysql' login account so that the server
     has read and write access to them when you run it later. To ensure
     this, the `--user' option should be used as shown if you run
     `mysql_install_db' as `root'. Otherwise, you should execute the
     script while logged in as `mysql', in which case you can omit the
     `--user' option from the command.

     `mysql_install_db' creates several tables in the `mysql' database:
     `user', `db', `host', `tables_priv', `columns_priv', `func', and
     possibly others depending on your version of MySQL.

     If you don't want to have the `test' database, you can remove it
     with `mysqladmin -u root drop test' after starting the server.

     If you have problems with `mysql_install_db', see *Note
     `mysql_install_db': mysql_install_db.

     There are some alternatives to running the `mysql_install_db'
     script as it is provided in the MySQL distribution:

        * If you want the initial privileges to be different from the
          standard defaults, you can modify `mysql_install_db' before
          you run it.  However, a preferable technique is to use
          `GRANT' and `REVOKE' to change the privileges after the grant
          tables have been set up.  In other words, you can run
          `mysql_install_db', and then use `mysql -u root mysql' to
          connect to the server as the MySQL `root' user so that you
          can issue the `GRANT' and `REVOKE' statements.

          If you want to install MySQL on a lot of machines with the
          same privileges, you can put the `GRANT' and `REVOKE'
          statements in a file and execute the file as a script using
          `mysql' after running `mysql_install_db'. For example:

               shell> bin/mysql_install_db --user=mysql
               shell> bin/mysql -u root < your_script_file

          By doing this, you can avoid having to issue the statements
          manually on each machine.

        * It is possible to re-create the grant tables completely after
          they have already been created.  You might want to do this if
          you're just learning how to use `GRANT' and `REVOKE' and have
          made so many modifications after running `mysql_install_db'
          that you want to wipe out the tables and start over.

          To re-create the grant tables, remove all the `.frm', `.MYI',
          and `.MYD' files in the directory containing the `mysql'
          database.  (This is the directory named `mysql' under the
          data directory, which is listed as the `datadir' value when
          you run `mysqld --help'.) Then run the `mysql_install_db'
          script again.

          *Note*: For MySQL versions older than 3.22.10, you should not
          delete the `.frm' files.  If you accidentally do this, you
          should copy them back into the `mysql' directory from your
          MySQL distribution before running `mysql_install_db'.

        * You can start `mysqld' manually using the
          `--skip-grant-tables' option and add the privilege
          information yourself using `mysql':

               shell> bin/mysqld_safe --user=mysql --skip-grant-tables &
               shell> bin/mysql mysql

          From `mysql', manually execute the SQL commands contained in
          `mysql_install_db'.  Make sure that you run `mysqladmin
          flush-privileges' or `mysqladmin reload' afterward to tell
          the server to reload the grant tables.

          Note that by not using `mysql_install_db', you not only have
          to populate the grant tables manually, you also have to
          create them first.

  3. Start the MySQL server:

          shell> bin/mysqld_safe --user=mysql &

     For versions of MySQL older than 4.0, substitute `bin/safe_mysqld'
     for `bin/mysqld_safe' in this command.

     It is important that the MySQL server be run using an unprivileged
     (non-`root') login account.  To ensure this, the `--user' option
     should be used as shown if you run `mysql_safe' as `root'.
     Otherwise, you should execute the script while logged in as
     `mysql', in which case you can omit the `--user' option from the
     command.

     Further instructions for running MySQL as an unprivileged user are
     given in *Note Changing MySQL user::.

     If you neglected to create the grant tables before proceeding to
     this step, the following message will appear in the error log file
     when you start the server:

          mysqld: Can't find file: 'host.frm'

     If you have other problems starting the server, see *Note Starting
     server::.

  4. Use `mysqladmin' to verify that the server is running.  The
     following commands provide simple tests to check whether the
     server is up and responding to connections:

          shell> bin/mysqladmin version
          shell> bin/mysqladmin variables

     The output from `mysqladmin version' varies slightly depending on
     your platform and version of MySQL, but should be similar to that
     shown here:

          shell> bin/mysqladmin version
          mysqladmin  Ver 8.40 Distrib 4.0.18, for linux on i586
          Copyright (C) 2000 MySQL AB & MySQL Finland AB & TCX DataKonsult AB
          This software comes with ABSOLUTELY NO WARRANTY. This is free software,
          and you are welcome to modify and redistribute it under the GPL license

          Server version          4.0.18-log
          Protocol version        10
          Connection              Localhost via Unix socket
          TCP port                3306
          UNIX socket             /tmp/mysql.sock
          Uptime:                 16 sec

          Threads: 1  Questions: 9  Slow queries: 0
          Opens: 7  Flush tables: 2  Open tables: 0
          Queries per second avg: 0.000
          Memory in use: 132K  Max memory used: 16773K

     To see what else you can do with `mysqladmin', invoke it with the
     `--help' option.

  5. Verify that you can shut down the server:

          shell> bin/mysqladmin -u root shutdown

  6. Verify that you can restart the server.  Do this by using
     `mysqld_safe' or by invoking `mysqld' directly.  For example:

          shell> bin/mysqld_safe --user=mysql --log &

     If `mysqld_safe' fails, see *Note Starting server::.

  7. Run some simple tests to verify that you can retrieve information
     from the server.  The output should be similar to what is shown
     here:

          shell> bin/mysqlshow
          +-----------+
          | Databases |
          +-----------+
          | mysql     |
          | test      |
          +-----------+

          shell> bin/mysqlshow mysql
          Database: mysql
          +--------------+
          |    Tables    |
          +--------------+
          | columns_priv |
          | db           |
          | func         |
          | host         |
          | tables_priv  |
          | user         |
          +--------------+

          shell> bin/mysql -e "SELECT Host,Db,User FROM db" mysql
          +------+--------+------+
          | host | db     | user |
          +------+--------+------+
          | %    | test   |      |
          | %    | test_% |      |
          +------+--------+------+

  8. There is a benchmark suite in the `sql-bench' directory (under the
     MySQL installation directory) that you can use to compare how
     MySQL performs on different platforms. The benchmark suite is
     written in Perl. It uses the Perl DBI module to provide a
     database-independent interface to the various databases, and some
     other additional Perl modules are required to run the benchmark
     suite. You must have the following modules installed:

          DBI
          DBD::mysql
          Data::Dumper
          Data::ShowTable

     These modules can be obtained from CPAN (`http://www.cpan.org/').
     *Note Perl installation::.

     The `sql-bench/Results' directory contains the results from many
     runs against different databases and platforms.  To run all tests,
     execute these commands:

          shell> cd sql-bench
          shell> perl run-all-tests

     If you don't have the `sql-bench' directory, you probably
     installed MySQL using RPM files other than the source RPM.  (The
     source RPM includes the `sql-bench' benchmark directory.)  In this
     case, you must first install the benchmark suite before you can
     use it.  Beginning with MySQL 3.22, there are separate benchmark
     RPM files named `mysql-bench-VERSION-i386.rpm' that contain
     benchmark code and data.

     If you have a source distribution, there are also tests in its
     `tests' subdirectory that you can run. For example, to run
     `auto_increment.tst', execute this command from the top-level
     directory of your source distribution:

          shell> mysql -vvf test < ./tests/auto_increment.tst

     The expected result of the test can be found in the
     `./tests/auto_increment.res' file.

  9. At this point, you should have the server running. However, none
     of the initial MySQL accounts have a password, so you should
     assign passwords using the instructions in *Note Default
     privileges::.

As of MySQL 4.1.3, the installation procedure creates time zone tables
in the `mysql' database. However, you must populate the tables manually.
Instructions to do this are given in *Note Time zone support::.

Problems Running `mysql_install_db'
...................................

The purpose of the `mysql_install_db' script is to generate new MySQL
privilege tables.  It will not overwrite existing MySQL privilege
tables, and it will not affect any other data.

If you want to re-create your privilege tables, first stop the `mysqld'
server if it's running. Then rename the `mysql' directory under the
data directory to save it, and then run `mysql_install_db'.  For
example:

     shell> mv mysql-data-directory/mysql mysql-data-directory/mysql-old
     shell> mysql_install_db --user=mysql

This section lists problems you might encounter when you run
`mysql_install_db':

*`mysql_install_db' doesn't install the grant tables*
     You may find that `mysql_install_db' fails to install the grant
     tables and terminates after displaying the following messages:

          Starting mysqld daemon with databases from XXXXXX
          mysqld ended

     In this case, you should examine the error log file very
     carefully.  The log should be located in the directory `XXXXXX'
     named by the error message, and should indicate why `mysqld'
     didn't start.  If you don't understand what happened, include the
     log when you post a bug report.  *Note Bug reports::.

*There is already a `mysqld' process running*
     This indicates that the server is already running, in which case
     the grant tables probably have already been created. If so, you
     don't have to run `mysql_install_db' at all because it need be run
     only once (when you install MySQL the first time).

*Installing a second `mysqld' server doesn't work when one server is running*
     This can happen when you already have an existing MySQL
     installation, but want to put a new installation in a different
     location.  For example, you might have a production installation
     already, but you want to create a second installation for testing
     purposes.  Generally the problem that occurs when you try to run a
     second server is that it tries to use a network interface that is
     already in use by the first server.  In this case, you will see
     one of the following error messages:

          Can't start server: Bind on TCP/IP port:
          Address already in use
          Can't start server: Bind on unix socket...

     For instructions on setting up multiple servers, see *Note
     Multiple servers::.

*You don't have write access to `/tmp'*
     If you don't have write access to create temporary files or a Unix
     socket file in the default location (the `/tmp' directory), an
     error will occur when you run `mysql_install_db' or the `mysqld'
     server.

     You can specify different temporary directory and Unix socket file
     locations by executing these commands prior to starting
     `mysql_install_db' or `mysqld':

          shell> TMPDIR=/some_tmp_dir/
          shell> MYSQL_UNIX_PORT=/some_tmp_dir/mysql.sock
          shell> export TMPDIR MYSQL_UNIX_PORT

     `some_tmp_dir' should be the full pathname to some directory for
     which you have write permission.

     After this, you should be able to run `mysql_install_db' and start
     the server with these commands:

          shell> bin/mysql_install_db --user=mysql
          shell> bin/mysqld_safe --user=mysql &

     If `mysql_install_db' is located in the `scripts' directory,
     modify the first command to use `scripts/mysql_install_db'.

     See *Note Problems with `mysql.sock': Problems with mysql.sock.
     *Note Environment variables::.

Starting and Stopping MySQL Automatically
.........................................

Generally, you start the `mysqld' server in one of these ways:

   * By invoking `mysqld' directly. This works on any platform.

   * By running the MySQL server as a Windows service.  This can be
     done on versions of Windows that support services (such as NT,
     2000, and XP). The service can be set to start the server
     automatically when Windows starts, or as a manual service that you
     start on request.  For instructions, see *Note NT start::.

   * By invoking `mysqld_safe', which tries to determine the proper
     options for `mysqld' and then runs it with those options.  This
     script is used on systems based on BSD Unix.  *Note `mysqld_safe':
     mysqld_safe.

   * By invoking `mysql.server'.  This script is used primarily at
     system startup and shutdown on systems that use System V-style run
     directories, where it usually is installed under the name `mysql'.
     The `mysql.server' script starts the server by invoking
     `mysqld_safe'.  *Note `mysql.server': mysql.server.

   * On Mac OS X, you can install a separate MySQL Startup Item package
     to enable the automatic startup of MySQL on system startup.  The
     Startup Item starts the server by invoking `mysql.server'.  See
     *Note Mac OS X installation:: for details.


The `mysql.server' and `mysqld_safe' scripts and the Mac OS X Startup
Item can be used to start the server manually, or automatically at
system startup time. `mysql.server' and the Startup Item also can be
used to stop the server.

To start or stop the server manually using the `mysql.server' script,
invoke it with `start' or `stop' arguments:

     shell> mysql.server start
     shell> mysql.server stop

Before `mysql.server' starts the server, it changes location to the
MySQL installation directory, and then invokes `mysqld_safe'.  If you
want the server to run as some specific user, add an appropriate `user'
option to the `[mysqld]' group of the `/etc/my.cnf' option file, as
shown later in this section.  (It is possible that you'll need to edit
`mysql.server' if you've installed a binary distribution of MySQL in a
non-standard location.  Modify it to `cd' into the proper directory
before it runs `mysqld_safe'.  If you do this, your modified version of
`mysql.server' may be overwritten if you upgrade MySQL in the future,
so you should make a copy of your edited version that you can
reinstall.)

`mysql.server stop' brings down the server by sending a signal to it.
You can also stop the server manually by executing `mysqladmin
shutdown'.

To start and stop MySQL automatically on your server, you need to add
start and stop commands to the appropriate places in your `/etc/rc*'
files.

If you use the Linux server RPM package (`MySQL-server-VERSION.rpm'),
the `mysql.server' script will already have been installed in the
`/etc/init.d' directory with the name `mysql'. You need not install it
manually. See *Note Linux-RPM:: for more information on the Linux RPM
packages.

Some vendors provide RPM packages that install a startup script under a
different name such as `mysqld'.

If you install MySQL from a source distribution or using a binary
distribution format that does not install `mysql.server' automatically,
you can install it manually. The script can be found in the
`support-files' directory under the MySQL installation directory or in
a MySQL source tree.

To install `mysql.server' manually, copy it to the `/etc/init.d'
directory with the name `mysql', and then make it executable.  Do this
by changing location into the appropriate directory where
`mysql.server' is located and executing these commands:

     shell> cp mysql.server /etc/init.d/mysql
     shell> chmod +x /etc/init.d/mysql

Older Red Hat systems use the `/etc/rc.d/init.d' directory rather than
`/etc/init.d'. Adjust the preceding commands accordingly. Alternatively,
first create `/etc/init.d' as a symbolic link that points to
`/etc/rc.d/init.d':

     shell> cd /etc
     shell> ln -s rc.d/init.d .

After installing the script, the commands needed to activate it to run
at system startup depend on your operating system.  On Linux, you can
use `chkconfig':

     shell> chkconfig --add mysql

On some Linux systems, the following command also seems to be necessary
to fully enable the `mysql' script:

     shell> chkconfig --level 345 mysql on

On FreeBSD, startup scripts generally should go in
`/usr/local/etc/rc.d/'. The `rc(8)' manual page states that scripts in
this directory are executed only if their basename matches the `*.sh'
shell filename pattern.  Any other files or directories present within
the directory are silently ignored. In other words, on FreeBSD, you
should install the `mysql.server' script as
`/usr/local/etc/rc.d/mysql.server.sh' to enable automatic startup.

As an alternative to the preceding setup, some operating systems also
use `/etc/rc.local' or `/etc/init.d/boot.local' to start additional
services on startup. To start up MySQL using this method, you could
append a command like the one following to the appropriate startup file:

     /bin/sh -c 'cd /usr/local/mysql; ./bin/mysqld_safe --user=mysql &'

For other systems, consult your operating system documentation to see
how to install startup scripts.

You can add options for `mysql.server' in a global `/etc/my.cnf' file.
A typical `/etc/my.cnf' file might look like this:

     [mysqld]
     datadir=/usr/local/mysql/var
     socket=/var/tmp/mysql.sock
     port=3306
     user=mysql

     [mysql.server]
     basedir=/usr/local/mysql

The `mysql.server' script understands the following options: `basedir',
`datadir', and `pid-file'.  If specified, they _must_ be placed in an
option file, not on the command line.  `mysql.server' understands only
`start' and `stop' as command-line arguments.

The following table shows which option groups the server and each
startup script read from option files:

*Script*       *Option Groups*
`mysqld'       `[mysqld]', `[server]', `[mysqld-major-version]'
`mysql.server' `[mysqld]', `[mysql.server]'
`mysqld_safe'  `[mysqld]', `[server]', `[mysqld_safe]'

`[mysqld-major-version]' means that groups with names like
`[mysqld-4.0]', `[mysqld-4.1]', and `[mysqld-5.0]' will be read by
servers having versions 4.0.x, 4.1.x, 5.0.x, and so forth.  This
feature was added in MySQL 4.0.14. It can be used to specify options
that will be read only by servers within a given release series.

For backward compatibility, `mysql.server' also reads the
`[mysql_server]' group and `mysqld_safe' also reads the `[safe_mysqld]'
group. However, you should update your option files to use the
`[mysql.server]' and `[mysqld_safe]' groups instead when you begin
using MySQL 4.0 or later.

*Note Option files::.

Starting and Troubleshooting the MySQL Server
.............................................

If you have problems starting the server, here are some things you can
try:

   * Specify any special options needed by the storage engines you are
     using.

   * Make sure that the server knows where to find the data directory.

   * Make sure the server can use the data directory.  The ownership and
     permissions of the data directory and its contents must be set
     such that the server can access and modify them.

   * Check the error log to see why the server doesn't start.

   * Verify that the network interfaces the server wants to use are
     available.


Some storage engines have options that control their behavior.  You can
create a `my.cnf' file and set startup options for the engines you plan
to use.  If you are going to use storage engines that support
transactional tables (`InnoDB', `BDB'), be sure that you have them
configured the way you want before starting the server:

   * If you are using `InnoDB' tables, refer to the `InnoDB'-specific
     startup options.  In MySQL 3.23, you must configure `InnoDB'
     explicitly or the server will fail to start.  From MySQL 4.0 on,
     `InnoDB' uses default values for its configuration options if you
     specify none.  *Note `InnoDB' configuration: InnoDB configuration.

   * If you are using `BDB' (Berkeley DB) tables, you should familiarize
     yourself with the different `BDB'-specific startup options.  *Note
     BDB start::.


When the `mysqld' server starts, it changes location to the data
directory.  This is where it expects to find databases and where it
expects to write log files. On Unix, the server also writes the pid
(process ID) file in the data directory.

The data directory location is hardwired in when the server is compiled.
This is where the server looks for the data directory by default. If
the data directory is located somewhere else on your system, the server
will not work properly.  You can find out what the default path
settings are by invoking `mysqld' with the `--verbose' and `--help'
options.  (Prior to MySQL 4.1, omit the `--verbose' option.)

If the defaults don't match the MySQL installation layout on your
system, you can override them by specifying options on the command line
to `mysqld' or `mysqld_safe'. You can also list the options in an
option file.

To specify the location of the data directory explicitly, use the
`--datadir' option. However, normally you can tell `mysqld' the
location of the base directory under which MySQL is installed and it
will look for the data directory there.  You can do this with the
`--basedir' option.

To check the effect of specifying path options, invoke `mysqld' with
those options followed by the `--verbose' and `--help' options.  For
example, if you change location into the directory where `mysqld' is
installed, and then run the following command, it will show the effect
of starting the server with a base directory of `/usr/local':

     shell> ./mysqld --basedir=/usr/local --verbose --help

You can specify other options such as `--datadir' as well, but note
that `--verbose' and `--help' must be the last options.  (Prior to
MySQL 4.1, omit the `--verbose' option.)

Once you determine the path settings you want, start the server without
`--verbose' and `--help'.

If `mysqld' is currently running, you can find out what path settings
it is using by executing this command:

     shell> mysqladmin variables

Or:

     shell> mysqladmin -h HOST_NAME variables

HOST_NAME is the name of the MySQL server host.

If you get `Errcode 13' (which means `Permission denied') when starting
`mysqld', this means that the access privileges of the data directory
or its contents do not allow the server access.  In this case, you
change the permissions for the involved files and directories so that
the server has the right to use them.  You can also start the server as
`root', but this can raise security issues and should be avoided.

On Unix, change location into the data directory and check the
ownership of the data directory and its contents to make sure the
server has access. For example, if the data directory is
`/usr/local/mysql/var', use this command:

     shell> ls -la /usr/local/mysql/var

If the data directory or its files or subdirectories are not owned by
the account that you use for running the server, change their ownership
to that account:

     shell> chown -R mysql /usr/local/mysql/var
     shell> chgrp -R mysql /usr/local/mysql/var

If the server fails to start up correctly, check the error log file to
see if you can find out why.  Log files are located in the data
directory (typically `C:\mysql\data' on Windows, `/usr/local/mysql/data'
for a Unix binary distribution, and `/usr/local/var' for a Unix source
distribution).  Look in the data directory for files with names of the
form `HOST_NAME.err' and `HOST_NAME.log', where HOST_NAME is the name
of your server host. (Older servers on Windows use `mysql.err' as the
error log name.)  Then check the last few lines of these files.  On
Unix, you can use `tail' to display the last few lines:

     shell> tail HOST_NAME.err
     shell> tail HOST_NAME.log

The error log contains information that indicates why the server
couldn't start.  For example, you might see something like this in the
log:

     000729 14:50:10  bdb:  Recovery function for LSN 1 27595 failed
     000729 14:50:10  bdb:  warning: ./test/t1.db: No such file or directory
     000729 14:50:10  Can't init databases

This means that you didn't start `mysqld' with the `--bdb-no-recover'
option and Berkeley DB found something wrong with its own log files
when it tried to recover your databases.  To be able to continue, you
should move away the old Berkeley DB log files from the database
directory to some other place, where you can later examine them.  The
`BDB' log files are named in sequence beginning with `log.0000000001',
where the number increases over time.

If you are running `mysqld' with `BDB' table support and `mysqld' dumps
core at startup, this could be due to problems with the `BDB' recovery
log.  In this case, you can try starting `mysqld' with
`--bdb-no-recover'.  If that helps, then you should remove all `BDB'
log files from the data directory and try starting `mysqld' again
without the `--bdb-no-recover' option.

If either of the following errors occur, it means that some other
program (perhaps another `mysqld' server) is already using the TCP/IP
port or Unix socket file that `mysqld' is trying to use:

     Can't start server: Bind on TCP/IP port: Address already in use
     Can't start server: Bind on unix socket...

Use `ps' to determine whether you have another `mysqld' server running.
If so, shut down the server before starting `mysqld' again.  (If
another server is running, and you really want to run multiple servers,
you can find information about how to do so in *Note Multiple
servers::.)

If no other server is running, try to execute the command `telnet
your-host-name tcp-ip-port-number'.  (The default MySQL port number is
3306.) Then press Enter a couple of times.  If you don't get an error
message like `telnet: Unable to connect to remote host: Connection
refused', some other program is using the TCP/IP port that `mysqld' is
trying to use.  You'll need to track down what program this is and
disable it, or else tell `mysqld' to listen to a different port with the
`--port' option.  In this case, you'll also need to specify the port
number for client programs when connecting to the server via TCP/IP.

Another reason the port might be inaccessible is that you have a
firewall running that blocks connections to it. If so, modify the
firewall settings to allow access to the port.

If the server starts but you can't connect to it, you should make sure
that you have an entry in `/etc/hosts' that looks like this:

     127.0.0.1       localhost

This problem occurs only on systems that don't have a working thread
library and for which MySQL must be configured to use MIT-pthreads.

If you can't get `mysqld' to start, you can try to make a trace file to
find the problem by using the `--debug' option.  *Note Making trace
files::.

Securing the Initial MySQL Accounts
-----------------------------------

Part of the MySQL installation process is to set up the `mysql' database
containing the grant tables:

   * Windows distributions contain preinitialized grant tables that are
     installed automatically.

   * On Unix, the grant tables are populated by the `mysql_install_db'
     program. Some installation methods run this program for you.
     Others require that you execute it manually. For details, see
     *Note Unix post-installation::.

The grant tables define the initial MySQL user accounts and their access
privileges.  These accounts are set up as follows:

   * Two accounts are created with a username of `root'.  These are
     superuser accounts that can do anything.  The initial `root'
     account passwords are empty, so anyone can connect to the MySQL
     server as `root' _without a password_ and be granted all
     privileges.

        * On Windows, one `root' account is for connecting from the
          local host and the other allows connections from any host.

        * On Unix, both `root' accounts are for connections from the
          local host.  Connections must be made from the local host by
          specifying a hostname of `localhost' for one account, or the
          actual hostname or IP number for the other.


   * Two anonymous-user accounts are created, each with an empty
     username.  The anonymous accounts have no passwords, so anyone can
     use them to connect to the MySQL server.

        * On Windows, one anonymous account is for connections from the
          local host.  It has all privileges, just like the `root'
          accounts.  The other is for connections from any host and has
          all privileges for the `test' database or other databases
          with names that start with `test'.

        * On Unix, both anonymous accounts are for connections from the
          local host.  Connections must be made from the local host by
          specifying a hostname of `localhost' for one account, or the
          actual hostname or IP number for the other.  These accounts
          have all privileges for the `test' database or other
          databases with names that start with `test_'.



As noted, none of the initial accounts have passwords.  This means that
your MySQL installation is unprotected until you do something about it:

   * If you want to prevent clients from connecting as anonymous users
     without a password, you should either assign passwords to the
     anonymous accounts or else remove them.

   * You should assign passwords to the MySQL `root' accounts.


The following instructions describe how to set up passwords for the
initial MySQL accounts, first for the anonymous accounts and then for
the `root' accounts.  Replace "NEWPWD" in the examples with the actual
password that you want to use.  The instructions also cover how to
remove the anonymous accounts, should you prefer not to allow anonymous
access at all.

You might want to defer setting the passwords until later, so that you
don't need to specify them while you perform additional setup or
testing.  However, be sure to set them before using your installation
for any real production work.

To assign passwords to the anonymous accounts, you can use either `SET
PASSWORD' or `UPDATE'.  In both cases, be sure to encrypt the password
using the `PASSWORD()' function.

To use `SET PASSWORD' on Windows, do this:

     shell> mysql -u root
     mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('NEWPWD');
     mysql> SET PASSWORD FOR ''@'%' = PASSWORD('NEWPWD');

To use `SET PASSWORD' on Unix, do this:

     shell> mysql -u root
     mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('NEWPWD');
     mysql> SET PASSWORD FOR ''@'HOST_NAME' = PASSWORD('NEWPWD');

In the second `SET PASSWORD' statement, replace HOST_NAME with the name
of the server host.  This is the name that is specified in the `Host'
column of the non-`localhost' record for `root' in the `user' table.
If you don't know what hostname this is, issue the following statement
before using `SET PASSWORD':

     mysql> SELECT Host, User FROM mysql.user;

Look for the record that has `root' in the `User' column and something
other than `localhost' in the `Host' column. Then use that `Host' value
in the second `SET PASSWORD' statement.

The other way to assign passwords to the anonymous accounts is by using
`UPDATE' to modify the `user' table directly.  Connect to the server as
`root' and issue an `UPDATE' statement that assigns a value to the
`Password' column of the appropriate `user' table records.  The
procedure is the same for Windows and Unix.  The following `UPDATE'
statement assigns a password to both anonymous accounts at once:

     shell> mysql -u root
     mysql> UPDATE mysql.user SET Password = PASSWORD('NEWPWD')
         ->     WHERE User = '';
     mysql> FLUSH PRIVILEGES;

After you update the passwords in the `user' table directly using
`UPDATE', you must tell the server to re-read the grant tables with
`FLUSH PRIVILEGES'. Otherwise, the change will go unnoticed until you
restart the server.

If you prefer to remove the anonymous accounts instead, do so as
follows:

     shell> mysql -u root
     mysql> DELETE FROM mysql.user WHERE User = '';
     mysql> FLUSH PRIVILEGES;

The `DELETE' statement applies both to Windows and to Unix.  On
Windows, if you want to remove only the anonymous account that has the
same privileges as `root', do this instead:

     shell> mysql -u root
     mysql> DELETE FROM mysql.user WHERE Host='localhost' AND User='';
     mysql> FLUSH PRIVILEGES;

This account allows anonymous access but has full privileges, so
removing it improves security.

You can assign passwords to the `root' accounts in several ways. The
following discussion demonstrates three methods:

   * Use the `SET PASSWORD' statement

   * Use the `mysqladmin' command-line client program

   * Use the `UPDATE' statement

To assign passwords using `SET PASSWORD', connect to the server as
`root' and issue two `SET PASSWORD' statements.  Be sure to encrypt the
password using the `PASSWORD()' function.

For Windows, do this:

     shell> mysql -u root
     mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('NEWPWD');
     mysql> SET PASSWORD FOR 'root'@'%' = PASSWORD('NEWPWD');

For Unix, do this:

     shell> mysql -u root
     mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('NEWPWD');
     mysql> SET PASSWORD FOR 'root'@'HOST_NAME' = PASSWORD('NEWPWD');

In the second `SET PASSWORD' statement, replace HOST_NAME with the name
of the server host.  This is the same hostname that you used when you
assigned the anonymous account passwords.

To assign passwords to the `root' accounts using `mysqladmin', execute
the following commands:

     shell> mysqladmin -u root password "NEWPWD"
     shell> mysqladmin -u root -h HOST_NAME password "NEWPWD"

These commands apply both to Windows and to Unix.  In the second
command, replace HOST_NAME with the name of the server host.  The double
quotes around the password are not always necessary, but you should use
them if the password contains spaces or other characters that are
special to your command interpreter.

If you are using a server from a _very_ old version of MySQL, the
`mysqladmin' commands to set the password will fail with the message
`parse error near 'SET password''.  The solution to this problem is to
upgrade the server to a newer version of MySQL.

You can also use `UPDATE' to modify the `user' table directly.  The
following `UPDATE' statement assigns a password to both `root' accounts
at once:

     shell> mysql -u root
     mysql> UPDATE mysql.user SET Password = PASSWORD('NEWPWD')
         ->     WHERE User = 'root';
     mysql> FLUSH PRIVILEGES;

The `UPDATE' statement applies both to Windows and to Unix.

After the passwords have been set, you must supply the appropriate
password whenever you connect to the server.  For example, if you want
to use `mysqladmin' to shut down the server, you can do so using this
command:

     shell> mysqladmin -u root -p shutdown
     Enter password: (enter root password here)

*Note*: If you forget your `root' password after setting it up, the
procedure for resetting it is covered in *Note Resetting permissions::.

To set up new accounts, you can use the `GRANT' statement. For
instructions, see *Note Adding users::.

Upgrading/Downgrading MySQL
===========================

As a general rule, we recommend that when upgrading from one release
series to another, you should go to the next series rather than
skipping a series. For example, if you currently are running MySQL 3.23
and wish to upgrade to a newer series, upgrade to MySQL 4.0 rather than
to 4.1 or 5.0.

The following items form a checklist of things you should do whenever
you perform an upgrade:

   * Read the upgrading section for the release series to which you are
     upgrading.  Read the change notes as well.  These provide
     information about new features you can use.  For example, before
     upgrading from MySQL 4.1 to 5.0, read the 5.0 upgrading section
     (*note Upgrading-from-4.1::) and read the 5.0 change notes (*note
     News::).

   * Before you do an upgrade, back up your databases.

   * If you are running MySQL Server on Windows, see *Note Windows
     upgrading::.

   * An upgrade may involve changes to the grant tables that are stored
     in the `mysql' database. Occasionally new columns or tables are
     added to support new features.  To take advantage of these
     features, be sure that your grant tables are up to date.  The
     upgrade procedure is described in *Note Upgrading-grant-tables::.

   * If you are using replication, see *Note Replication Upgrade:: for
     information on upgrading your replication setup.

   * If you install a MySQL-Max distribution that includes a server
     named `mysqld-max', then upgrade later to a non-Max version of
     MySQL, `mysqld_safe' will still attempt to run the old `mysqld-max'
     server.  If you perform such an upgrade, you should manually
     remove the old `mysqld-max' server to ensure that `mysqld_safe'
     runs the new `mysqld' server.


You can always move the MySQL format files and data files between
different versions on the same architecture as long as you stay within
versions for the same release series of MySQL. The current production
release series is 4.0. If you change the character set when running
MySQL, you must run `myisamchk -r -q --set-character-set=CHARSET' on
all `MyISAM' tables.  Otherwise, your indexes may not be ordered
correctly, because changing the character set may also change the sort
order.

If you upgrade or downgrade from one release series to another, there
may be incompatibilities in table storage formats. In this case, you
can use `mysqldump' to dump your tables before upgrading. After
upgrading, reload the dump file using `mysql' to re-create your tables.

If you are cautious about using new versions, you can always rename
your old `mysqld' before installing a newer one. For example, if you
are using MySQL 4.0.18 and want to upgrade to 4.1.1, rename your
current server from `mysqld' to `mysqld-4.0.18'.  If your new `mysqld'
then does something unexpected, you can simply shut it down and restart
with your old `mysqld'.

If, after an upgrade, you experience problems with recompiled client
programs, such as `Commands out of sync' or unexpected core dumps, you
probably have used old header or library files when compiling your
programs.  In this case, you should check the date for your `mysql.h'
file and `libmysqlclient.a' library to verify that they are from the new
MySQL distribution.  If not, recompile your programs with the new
headers and libraries.

If problems occur, such as that the new `mysqld' server doesn't want to
start or that you can't connect without a password, verify that you
don't have some old `my.cnf' file from your previous installation.  You
can check this with the `--print-defaults' option (for example, `mysqld
--print-defaults').  If this displays anything other than the program
name, you have an active `my.cnf' file that affects server or client
operation.

It is a good idea to rebuild and reinstall the Perl `DBD::mysql' module
whenever you install a new release of MySQL. The same applies to other
MySQL interfaces as well, such as the PHP `mysql' extension and the
Python `MySQLdb' module.

Upgrading from Version 4.1 to 5.0
---------------------------------

In general, you should do the following when upgrading to MySQL 5.0
from 4.1:

   * Check the items in the change list found later in this section to
     see whether any of them might affect your applications.

   * Read the 5.0 news items to see what significant new features you
     can use in 5.0.  *Note News-5.0.x::.

   * If you are running MySQL Server on Windows, see *Note Windows
     upgrading::.  Also, two of the Windows MySQL servers were renamed.
     *Note Windows select server::.

   * MySQL 5.0 adds support for stored procedures. This support
     requires the `proc' table in the `mysql' database.  To create this
     file, you should run the `mysql_fix_privilege_tables' script as
     described in *Note Upgrading-grant-tables::.

   * MySQL 5.0 adds support for views. This support requires the extra
     privilege columns in the `user' and `db' tables in the `mysql'
     database.  To create these columns, you should run the
     `mysql_fix_privilege_tables' script as described in *Note
     Upgrading-grant-tables::.

   * If you are using replication, see *Note Replication Upgrade:: for
     information on upgrading your replication setup.

   * MySQL 5.0.2 adds several new SQL modes that allow stricter control
     over rejecting records that have invalid or missing values.  *Note
     Server SQL mode::.  *Note constraint invalid data::.  If you want
     to enable this control but continue to use MySQL's capability for
     storing incorrect dates such as `'2004-02-31'', you should start
     the server with `--sql_mode=TRADITIONAL,ALLOW_INVALID_DATES'.

   * As of MySQL 5.0.2, the `SCHEMA' and `SCHEMAS' keywords are
     accepted as synonyms for `DATABASE' and `DATABASES'.

   * The update log is removed in MySQL 5.0.


The following list describes changes that may affect applications and
that you should watch out for when upgrading to version 5.0:

   * The update log is removed, so if you enabled it in the past, you
     should enable the binary log instead.  *Note News-5.0.x::.

   * User variables now are not case sensitive. In MySQL 4.1, `SET @x =
     0; SET @X = 1; SELECT @x;' creates two variables and returns `0'.
     In MySQL 5.0, it creates one variable and returns `1'.


Upgrading from Version 4.0 to 4.1
---------------------------------

In general, you should do the following when upgrading to MySQL 4.1
from 4.0:

   * Check the items in the change lists found later in this section to
     see whether any of them might affect your applications. Some of
     them result in incompatibilities with earlier versions.

   * Read the 4.1 news items to see what significant new features you
     can use in 4.1.  *Note News-4.1.x::.

   * Character set support has been improved. The server now supports
     multiple character sets.

   * *Important note:* MySQL 4.1 stores table names and column names in
     `UTF8'. If you have table names or column names that use
     characters outside of the standard 7-bit US-ASCII range, you may
     have to do a `mysqldump' of your tables in MySQL 4.0 and restore
     them after upgrading to MySQL 4.1.  The symptom for this problem
     is that you get a `table not found' error when trying to access
     your tables. In this case, you should be able to downgrade back to
     MySQL 4.0 and access your data.

   * If you are running MySQL Server on Windows, see *Note Windows
     upgrading::.

     *Important note:* Early alpha Windows distributions for MySQL 4.1
     do not contain an installer program.  See *Note Windows binary
     installation:: for instructions on how to install such a
     distribution.

   * After upgrading, update the grant tables to have the new longer
     `Password' column that is needed for more secure handling of
     passwords.  The procedure uses `mysql_fix_privilege_tables' and is
     described in *Note Upgrading-grant-tables::.  If you don't do
     this, MySQL will not us the new more secure protocol to
     authenticate.  Implications of the password-handling change for
     applications are given later in this section.

   * If you are using replication, see *Note Replication Upgrade:: for
     information on upgrading your replication setup.

   * The Berkeley DB table handler is updated to DB 4.1 (from 3.2)
     which has a new log format. If you have to downgrade back to 4.0
     you must use `mysqldump' to dump your `BDB' tables in text format
     and delete all `log.XXXXXXXXXX' files before you start MySQL 4.0
     and reload the data.

   * MySQL 4.1.3 introduces support for per-connection time zones.
     *Note Time zone support::. To enable recognition of named time
     zones, you should create the time zone tables in the `mysql'
     database.  For instructions, see *Note Post-installation::.

   * If you are using an old `DBD-mysql' module (`Msql-MySQL-modules')
     you have to upgrade to use the newer `DBD-mysql' module. Anything
     above `DBD-mysql' 2.xx should be fine.

     If you don't upgrade, some methods (such as `DBI->do()') will not
     notice error conditions correctly.

   * The `--defaults-file=option-file-name' option now will give an
     error if the option file doesn't exist.

   * Some notes about upgrading from MySQL 4.0 to MySQL 4.1 on Netware:
     Make sure to upgrade Perl and PHP versions. Download and install
     Perl module for MySQL 4.1 from
     `http://forge.novell.com/modules/xfmod/project/showfiles.php?group_id=1126'
     and PHP Extension for MySQL 4.1 from
     `http://forge.novell.com/modules/xfmod/project/showfiles.php?group_id=1078'.


Several visible behaviors have changed between MySQL 4.0 and MySQL 4.1
to fix some critical bugs and make MySQL more compatible with standard
SQL.  These changes may affect your applications.

Some of the 4.1 behaviors can be tested in 4.0 before performing a full
upgrade to 4.1. We have added to later MySQL 4.0 releases (from 4.0.12
on) a `--new' startup option for `mysqld'.  *Note Server options::.

This option gives you the 4.1 behavior for the most critical changes.
You can also enable these behaviors for a given client connection with
the `SET @@new=1' command, or turn them off if they are on with `SET
@@new=0'.

If you believe that some of the 4.1 changes will affect you, we
recommend that before upgrading to 4.1, you download the latest MySQL
4.0 version and run it with the `--new' option by adding the following
to your config file:

     [mysqld-4.0]
     new

That way you can test the new behaviors in 4.0 to make sure that your
applications work with them. This will help you have a smooth, painless
transition when you perform a full upgrade to 4.1 later. Putting the
`--new' option in the `[mysqld-4.0]' option group ensures that you
don't accidentally later run the 4.1 version with the `--new' option.

The following lists describe changes that may affect applications and
that you should watch out for when upgrading to version 4.1:

*Server Changes:*

   * All tables and string columns now have a character set.  *Note
     Charset::.  Character set information is displayed by `SHOW CREATE
     TABLE' and `mysqldump'.  (MySQL versions 4.0.6 and above can read
     the new dump files; older versions cannot.)  This change should
     not affect applications that use only one character set.

   * If you have table columns that store character data represented in
     a character set that the 4.1 server now supports directly, you can
     convert the columns to the proper character set using the
     instructions in *Note Charset-conversion::.  Also, database,
     table, and column identifiers now are stored internally using
     Unicode (UTF8) regardless of the default character set.  *Note
     Legal names::.

   * *Incompatible change:* Starting from MySQL 4.1.3, `InnoDB' uses
     the same character set comparison functions as MySQL for
     non-`latin1_swedish_ci' character strings that are not `BINARY'.
     This changes the sorting order of space and characters with a code
     < ASCII(32) in those character sets.  For `latin1_swedish_ci'
     character strings and `BINARY' strings, `InnoDB' uses its own
     pad-spaces-at-end comparison method, which stays unchanged.  If
     you have an `InnoDB' table created with MySQL 4.1.2 or earlier,
     with an index on a non-`latin1' character set (in the case of
     4.1.0 and 4.1.1, with any character set) and the table contains
     any `CHAR'/`VARCHAR'/or `TEXT' columns that are not `BINARY' but
     may contain characters with a code < ASCII(32), then you should do
     `ALTER TABLE' or `OPTIMIZE' table on it to *regenerate the index,
     after upgrading to MySQL 4.1.3 or later*.

   * *Incompatible change:* MySQL now interprets length specifications
     in character column definitions in characters. (Earlier versions
     interpret them in bytes.)  For example, `CHAR(N)' now means N
     characters, not N bytes.

     For single-byte character sets, this change makes no difference.
     However, if you upgrade to MySQL 4.1 and configure the server to
     use a multi-byte character set, the apparent length of character
     columns will change. Suppose that a 4.0 table contains a `CHAR(8)'
     column used to store `ujis' characters. Eight bytes can store from
     two to four `ujis' characters.  If you upgrade to 4.1 and
     configure the server to use `ujis' as its default character set,
     the server interprets character column lengths based on the
     maximum size of a `ujis' character, which is three bytes.  The
     number of three-byte characters that fit in eight bytes is two.
     Consequently, if you use `SHOW CREATE TABLE' to view the table
     definition, MySQL displays `CHAR(2)'.  You can retrieve existing
     data from the table, but you will be able to store new values
     containing only up to two characters. To correct this issue, use
     `ALTER TABLE' to change the column definition. For example:

          ALTER TABLE TBL_NAME MODIFY COL_NAME CHAR(8);

   * The table definition format used in `.frm' files has changed
     slightly in 4.1.  MySQL 4.0 versions from 4.0.11 on can read the
     new `.frm' format directly, but older versions cannot.  If you
     need to move tables from 4.1 to a version earlier than 4.0.11, you
     should use `mysqldump'.  *Note `mysqldump': mysqldump.

   * *Important note:* If you upgrade to MySQL 4.1.1 or higher, it is
     difficult to downgrade back to 4.0 or 4.1.0! That is because, for
     earlier versions, `InnoDB' is not aware of multiple tablespaces.

   * *Incompatible change:* In connection with the support for
     per-connection time zones in MySQL 4.1.3, the `timezone' system
     variable was renamed to `system_time_zone'.

   * Windows servers now support connections from local clients using
     shared memory if run with the `--shared-memory' option.  If you
     are running multiple servers this way on the same Windows machine,
     you should use a different `--shared-memory-base-name' option for
     each server.

   * The interface to aggregated UDF functions has changed a bit. You
     must now declare a `xxx_clear()' function for each aggregate
     function `XXX()'.


*Client Changes:*

   * `mysqldump' now has the `--opt' and `--quote-names' options
     enabled by default. You can turn them off with `--skip-opt' and
     `--skip-quote-names'.


*SQL Changes:*

   * *Incompatible change:* In MySQL 4.1.2, the `Type' column in the
     output from `SHOW TABLE STATUS' was renamed to `Engine'.

   * *Incompatible change:* String comparison now works according to
     SQL standard: Instead of stripping end spaces before comparison,
     we now extend the shorter string with spaces.  The problem with
     this is that now `'a' > 'a\t'', which it wasn't before.  If you
     have any tables where you have a `CHAR' or `VARCHAR' column in
     which the last character in the column may be less than
     `ASCII(32)', you should use `REPAIR TABLE' or `myisamchk' to
     ensure that the table is correct.

   * When using multiple-table `DELETE' statements, you should use the
     alias of the tables from which you want to delete, not the actual
     table name.  For example, instead of doing this:

          DELETE test FROM test AS t1, test2 WHERE ...

     Do this:

          DELETE t1 FROM test AS t1, test2 WHERE ...

     This corrects a problem that was present in MySQL 4.0.

   * *Incompatible change:* `TIMESTAMP' is now returned as a string in
     `'YYYY-MM-DD HH:MM:SS'' format (from 4.0.12 the `--new' option can
     be used to make a 4.0 server behave as 4.1 in this respect).
     *Note `TIMESTAMP' 4.1: TIMESTAMP 4.1.

     If you want to have the value returned as a number (as MySQL 4.0
     does) you should add `+0' to `TIMESTAMP' columns when you retrieve
     them:

          mysql> SELECT ts_col + 0 FROM TBL_NAME;

     Display widths for `TIMESTAMP' columns are no longer supported.
     For example, if you declare a column as `TIMESTAMP(10)', the `(10)'
     is ignored.

     These changes were necessary for SQL standards compliance. In a
     future version, a further change will be made (backward compatible
     with this change), allowing the timestamp length to indicate the
     desired number of digits for fractions of a second.

   * *Incompatible change:* Binary values such as `0xFFDF' now are
     assumed to be strings instead of numbers.  This fixes some
     problems with character sets where it's convenient to input a
     string as a binary value.  With this change, you should use
     `CAST()' if you want to compare binary values numerically as
     integers:

          mysql> SELECT CAST(0xFEFF AS UNSIGNED INTEGER)
              ->        < CAST(0xFF AS UNSIGNED INTEGER);
                  -> 0

     If you don't use `CAST()', a lexical string comparison will be
     done:

          mysql> SELECT 0xFEFF < 0xFF;
                  -> 1

     Using binary items in a numeric context or comparing them using the
     `=' operator should work as before.  (The `--new' option can be
     used from 4.0.13 on to make a 4.0 server behave as 4.1 in this
     respect.)

   * For functions that produce a `DATE', `DATETIME', or `TIME' value,
     the result returned to the client now is fixed up to have a
     temporal type. For example, in MySQL 4.1, you get this result:

          mysql> SELECT CAST('2001-1-1' AS DATETIME);
                 -> '2001-01-01 00:00:00'

     In MySQL 4.0, the result is different:

          mysql> SELECT CAST('2001-1-1' AS DATETIME);
                 -> '2001-01-01'

   * `DEFAULT' values no longer can be specified for `AUTO_INCREMENT'
     columns. (In 4.0, a `DEFAULT' value is silently ignored; in 4.1,
     an error occurs.)

   * `LIMIT' no longer accepts negative arguments.  Use some large
     number (maximum 18446744073709551615) instead of -1.

   * `SERIALIZE' is no longer a valid mode value for the `sql_mode'
     variable.  You should use `SET TRANSACTION ISOLATION LEVEL
     SERIALIZABLE' instead. `SERIALIZE' is no longer valid for the
     `--sql-mode' option for `mysqld', either. Use
     `--transaction-isolation=SERIALIZABLE' instead.


*C API Changes:*

   * *Incompatible change:* The `mysql_shutdown()' C API function has
     an extra parameter as of MySQL 4.1.3: `SHUTDOWN'-level. You should
     convert any `mysql_shutdown(X)' call you have in your application
     to `mysql_shutdown(X,SHUTDOWN_DEFAULT)'.

   * Some C API calls such as `mysql_real_query()' now return `1' on
     error, not `-1'.  You may have to change some old applications if
     they use constructs like this:

          if (mysql_real_query(mysql_object, query, query_length) == -1)
          {
            printf("Got error");
          }

     Change the call to test for a non-zero value instead:

          if (mysql_real_query(mysql_object, query, query_length) != 0)
          {
            printf("Got error");
          }


*Password-Handling Changes:*

The password hashing mechanism has changed in 4.1 to provide better
security, but this may cause compatibility problems if you still have
clients that use the client library from 4.0 or earlier.  (It is very
likely that you will have 4.0 clients in situations where clients
connect from remote hosts that have not yet upgraded to 4.1.)  The
following list indicates some possible upgrade strategies.  They
represent various tradeoffs between the goal of compatibility with old
clients and the goal of security.

   * Only upgrade the client to use 4.1 client libraries (not the
     server). No behavior will change (except the return value of some
     API calls), but you cannot use any of the new features provided by
     the 4.1 client/server protocol, either.  (MySQL 4.1 has an
     extended client/server protocol that offers such features as
     prepared statements and multiple result sets.)  *Note C API
     Prepared statements::.

   * Upgrade to 4.1 and run the `mysql_fix_privilege_tables' script to
     widen the `Password' column in the `user' table so that it can
     hold long password hashes.  But run the server with the
     `--old-passwords' option to provide backward compatibility that
     allows pre-4.1 clients to continue to connect to their short-hash
     accounts.  Eventually, when all your clients are upgraded to 4.1,
     you can stop using the `--old-passwords' server option. You can
     also change the passwords for your MySQL accounts to use the new
     more secure format.

   * Upgrade to 4.1 and run the `mysql_fix_privilege_tables' script to
     widen the `Password' column in the `user' table.  If you know that
     all clients also have been upgraded to 4.1, don't run the server
     with the `--old-passwords' option.  Instead, change the passwords
     on all existing accounts so that they have the new format.  A
     pure-4.1 installation is the most secure.

   * Some notes about upgrading from MySQL 4.0 to MySQL 4.1 on Netware:
     Make sure to upgrade Perl and PHP versions. Download Perl 5 for
     Netware from http://forge.novell.com/modules/xfmod/project/?perl5)
     and PHP from http://forge.novell.com/modules/xfmod/project/?php.


Further background on password hashing with respect to client
authentication and password-changing operations may be found in *Note
Password hashing:: and *Note Old client::.

Upgrading from Version 3.23 to 4.0
----------------------------------

In general, you should do the following when upgrading to MySQL 4.0
from 3.23:

   * Check the items in the change lists found later in this section to
     see whether any of them might affect your applications.

   * Read the 4.0 news items to see what significant new features you
     can use in 4.0.  *Note News-4.0.x::.

   * If you are running MySQL Server on Windows, see *Note Windows
     upgrading::.

   * After upgrading, update the grant tables to add new privileges and
     features.  The procedure uses the `mysql_fix_privilege_tables'
     script and is described in *Note Upgrading-grant-tables::.

   * If you are using replication, see *Note Replication Upgrade:: for
     information on upgrading your replication setup.

   * Edit any MySQL startup scripts or option files to not use any of
     the deprecated options described later in this section.

   * Convert your old `ISAM' files to `MyISAM' files. One way to do this
     is with the `mysql_convert_table_format' script. (This is a Perl
     script; it requires that DBI be installed.) To convert the tables
     in a given database, use this command:

          shell> mysql_convert_table_format database DB_NAME

     Note that this should be used only if all tables in the given
     database are `ISAM' or `MyISAM' tables. To avoid converting tables
     of other types to `MyISAM', you can explicitly list the names of
     your `ISAM' tables after the database name on the command line.

     Individual tables can be changed to `MyISAM' by using the following
     `ALTER TABLE' statement for each table to be converted:

          mysql> ALTER TABLE TBL_NAME TYPE=MyISAM;

     If you are not sure of the table type for a given table, use this
     statement:

          mysql> SHOW TABLE STATUS LIKE 'TBL_NAME';

   * Ensure that you don't have any MySQL clients that use shared
     libraries (like the Perl `DBD::mysql' module). If you do, you
     should recompile them, because the data structures used in
     `libmysqlclient.so' have changed.  The same applies to other MySQL
     interfaces as well, such as the Python `MySQLdb' module.


MySQL 4.0 will work even if you don't perform the preceding actions,
but you will not be able to use the new security privileges in MySQL
4.0 and you may run into problems when upgrading later to MySQL 4.1 or
newer.  The `ISAM' file format still works in MySQL 4.0, but is
deprecated and is not compiled in by default as of MySQL 4.1. `MyISAM'
tables should be used instead.

Old clients should work with a MySQL 4.0 server without any problems.

Even if you perform the preceding actions, you can still downgrade to
MySQL 3.23.52 or newer if you run into problems with the MySQL 4.0
series.  In this case, you must use `mysqldump' to dump any tables that
use full-text indexes and reload the dump file into the 3.23 server.
This is necessary because 4.0 uses a new format for full-text indexing.

The following lists describe changes that may affect applications and
that you should watch out for when upgrading to version 4.0:

*Server Changes:*

   * MySQL 4.0 has a lot of new privileges in the `mysql.user' table.
     *Note Privileges provided::.

     To get these new privileges to work, you must update the grant
     tables.  The procedure is described in *Note
     Upgrading-grant-tables::.  Until you do this, all accounts have
     the `SHOW DATABASES', `CREATE TEMPORARY TABLES', and `LOCK TABLES'
     privileges. `SUPER' and `EXECUTE' privileges take their value from
     `PROCESS'.  `REPLICATION SLAVE' and `REPLICATION CLIENT' take their
     values from `FILE'.

     If you have any scripts that create new MySQL user accounts, you
     may want to change them to use the new privileges.  If you are not
     using `GRANT' commands in the scripts, this is a good time to
     change your scripts to use `GRANT' instead of modifying the grant
     tables directly.

     From version 4.0.2 on, the option `--safe-show-database' is
     deprecated (and no longer does anything). *Note Privileges
     options::.

     If you get `Access denied' errors for new users in version 4.0.2
     and up, you should check whether you need some of the new grants
     that you didn't need before.  In particular, you will need
     `REPLICATION SLAVE' (instead of `FILE') for new slave servers.

   * `safe_mysqld' has been renamed to `mysqld_safe'.  For backward
     compatibility, binary distributions will for some time include
     `safe_mysqld' as a symlink to `mysqld_safe'.

   * `InnoDB' support is now included by default in binary
     distributions.  If you build MySQL from source, `InnoDB' is
     configured in by default.  If you do not use `InnoDB' and want to
     save memory when running a server that has `InnoDB' support
     enabled, use the `--skip-innodb' server startup option. To compile
     MySQL without `InnoDB' support, run `configure' with the
     `--without-innodb' option.

   * Values for the startup parameters
     `myisam_max_extra_sort_file_size' and
     `myisam_max_extra_sort_file_size' now are given in bytes (they
     were given in megabytes before 4.0.3).

   * `mysqld' now has the option `--temp-pool' enabled by default
     because this gives better performance with some operating systems
     (most notably Linux).

   * The `mysqld' startup options `--skip-locking' and
     `--enable-locking' were renamed to `--skip-external-locking' and
     `--external-locking'.

   * External system locking of `MyISAM'/`ISAM' files is now turned off
     by default.  You can turn this on with `--external-locking'.
     (However, this is never needed for most users.)

   * The following startup variables and options have been renamed:

     *Old Name*                         *New Name*
     `myisam_bulk_insert_tree_size'     `bulk_insert_buffer_size'
     `query_cache_startup_type'         `query_cache_type'
     `record_buffer'                    `read_buffer_size'
     `record_rnd_buffer'                `read_rnd_buffer_size'
     `sort_buffer'                      `sort_buffer_size'
     `warnings'                         `log-warnings'
     `--err-log'                        `--log-error' (for `mysqld_safe')

     The startup options `record_buffer', `sort_buffer', and `warnings'
     will still work in MySQL 4.0 but are deprecated.

*SQL Changes:*

   * The following SQL variables have been renamed:

     *Old Name*                         *New Name*
     `SQL_BIG_TABLES'                   `BIG_TABLES'
     `SQL_LOW_PRIORITY_UPDATES'         `LOW_PRIORITY_UPDATES'
     `SQL_MAX_JOIN_SIZE'                `MAX_JOIN_SIZE'
     `SQL_QUERY_CACHE_TYPE'             `QUERY_CACHE_TYPE'
     The old names still work in MySQL 4.0 but are deprecated.

   * You have to use `SET GLOBAL SQL_SLAVE_SKIP_COUNTER=skip_count'
     instead of `SET SQL_SLAVE_SKIP_COUNTER=skip_count'.

   * `SHOW MASTER STATUS' now returns an empty set if binary logging is
     not enabled.

   * `SHOW SLAVE STATUS' now returns an empty set if the slave is not
     initialized.

   * `SHOW INDEX' has two more columns than it had in 3.23 (`Null' and
     `Index_type').

   * The format of `SHOW OPEN TABLES' has changed.

   * `ORDER BY col_name DESC' sorts `NULL' values last, as of MySQL
     4.0.11. In 3.23 and in earlier 4.0 versions, this was not always
     consistent.

   * `CHECK', `LOCALTIME', and `LOCALTIMESTAMP' now are reserved words.

   * `DOUBLE' and `FLOAT' columns now honor the `UNSIGNED' flag on
     storage (before, `UNSIGNED' was ignored for these columns).

   * The result of all bitwise operators (`|', `&', `<<', `>>', and
     `~') is now unsigned.  This may cause problems if you are using
     them in a context where you want a signed result.  *Note Cast
     Functions::.

     *Note*: When you use subtraction between integer values where one
     is of type `UNSIGNED', the result will be unsigned.  In other
     words, before upgrading to MySQL 4.0, you should check your
     application for cases in which you are subtracting a value from an
     unsigned entity and want a negative answer or subtracting an
     unsigned value from an integer column. You can disable this
     behavior by using the `--sql-mode=NO_UNSIGNED_SUBTRACTION' option
     when starting `mysqld'.  *Note Server SQL mode::.

   * You should use integers to store values in `BIGINT' columns
     (instead of using strings, as you did in MySQL 3.23).  Using
     strings will still work, but using integers is more efficient.

   * In MySQL 3.23, `INSERT INTO ... SELECT' always had `IGNORE'
     enabled.  As of 4.0.1, MySQL will stop (and possibly roll back) by
     default in case of an error unless you specify `IGNORE'.

   * You should use `TRUNCATE TABLE' when you want to delete all rows
     from a table and you don't need to obtain a count of the number of
     rows that were deleted.  (`DELETE FROM TBL_NAME' returns a row
     count in 4.0 and doesn't reset the `AUTO_INCREMENT' counter, and
     `TRUNCATE TABLE' is faster.)

   * You will get an error if you have an active transaction or `LOCK
     TABLES' statement when trying to execute `TRUNCATE TABLE' or `DROP
     DATABASE'.

   * To use `MATCH ... AGAINST (... IN BOOLEAN MODE)' full-text searches
     with your tables, you must rebuild their indexes with `REPAIR TABLE
     tbl_name USE_FRM'.  If you attempt a boolean full-text search
     without rebuilding the indexes this way, the search will return
     incorrect results.  *Note Fulltext Fine-tuning::.

   * `LOCATE()' and `INSTR()' are case sensitive if one of the
     arguments is a binary string. Otherwise they are case insensitive.

   * `STRCMP()' now uses the current character set when performing
     comparisons.  This makes the default comparison behavior not case
     sensitive unless one or both of the operands are binary strings.

   * `HEX(STR)' now returns the characters in STR converted to
     hexadecimal.  If you want to convert a number to hexadecimal, you
     should ensure that you call `HEX()' with a numeric argument.

   * `RAND(seed)' returns a different random number series in 4.0 than
     in 3.23; this was done to further differentiate `RAND(seed)' and
     `RAND(seed+1)'.

   * The default type returned by `IFNULL(A,B)' is now set to be the
     more "general" of the types of `A' and `B'. (The
     general-to-specific order is string, `REAL', `INTEGER').


*C API Changes:*

   * The old C API functions `mysql_drop_db()', `mysql_create_db()', and
     `mysql_connect()' are no longer supported unless you compile MySQL
     with `CFLAGS=-DUSE_OLD_FUNCTIONS'.  However, it is preferable to
     change client programs to use the new 4.0 API instead.

   * In the `MYSQL_FIELD' structure, `length' and `max_length' have
     changed from `unsigned int' to `unsigned long'. This should not
     cause any problems, except that they may generate warning messages
     when used as arguments in the `printf()' class of functions.

   * Multi-threaded clients should use `mysql_thread_init()' and
     `mysql_thread_end()'. *Note Threaded clients::.


*Other Changes:*

   * If you want to recompile the Perl `DBD::mysql' module, use a recent
     version.  Version 2.9003 is recommended. Versions older than
     1.2218 should not be used because they use the deprecated
     `mysql_drop_db()' call.


Upgrading from Version 3.22 to 3.23
-----------------------------------

MySQL 3.22 and 3.21 clients will work without any problems with a MySQL
3.23 server.

When upgrading to MySQL 3.23 from an earlier version, note the following
changes:

*Table Changes:*

   * MySQL 3.23 supports tables of the new `MyISAM' type and the old
     `ISAM' type.  By default, all new tables are created with type
     `MyISAM' unless you start `mysqld' with the
     `--default-table-type=isam' option.  You don't have to convert
     your old `ISAM' tables to use them with MySQL 3.23.  You can
     convert an `ISAM' table to `MyISAM' format with `ALTER TABLE
     TBL_NAME TYPE=MyISAM' or the Perl script
     `mysql_convert_table_format'.

   * All tables that use the `tis620' character set must be fixed with
     `myisamchk -r' or `REPAIR TABLE'.

   * If you are using the `german' character sort order for `ISAM'
     tables, you must repair them with `isamchk -r', because we have
     made some changes in the sort order.


*Client Program Changes:*

   * The MySQL client `mysql' is now by default started with the
     `--no-named-commands (-g)' option. This option can be disabled with
     `--enable-named-commands (-G)'. This may cause incompatibility
     problems in some cases--for example, in SQL scripts that use named
     commands without a semicolon.  Long format commands still work
     from the first line.

   * If you want your `mysqldump' files to be compatible between MySQL
     3.22 and 3.23, you should not use the `--opt' or `--all' option to
     `mysqldump'.


*SQL Changes:*

   * If you do a `DROP DATABASE' on a symbolically linked database,
     both the link and the original database are deleted.  This didn't
     happen in MySQL 3.22 because `configure' didn't detect the
     availability of the `readlink()' system call.

   * `OPTIMIZE TABLE' now works only for `MyISAM' tables.  For other
     table types, you can use `ALTER TABLE' to optimize the table.
     During `OPTIMIZE TABLE', the table is now locked to prevent it
     from being used by other threads.

   * Date functions that work on parts of dates (such as `MONTH()')
     will now return 0 for `0000-00-00' dates. In MySQL 3.22, these
     functions returned `NULL'.

   * The default return type of `IF()' now depends on both arguments,
     not just the first one.

   * `AUTO_INCREMENT' columns should not be used to store negative
     numbers. The reason for this is that negative numbers caused
     problems when wrapping from -1 to 0.  You should not store 0 in
     `AUTO_INCREMENT' columns, either; `CHECK TABLE' will complain
     about 0 values because they may change if you dump and restore the
     table.  `AUTO_INCREMENT' for `MyISAM' tables is now handled at a
     lower level and is much faster than before. In addition, for
     `MyISAM' tables, old numbers are no longer reused, even if you
     delete rows from the table.

   * `CASE', `DELAYED', `ELSE', `END', `FULLTEXT', `INNER', `RIGHT',
     `THEN', and `WHEN' now are reserved words.

   * `FLOAT(p)' now is a true floating-point type and not a value with a
     fixed number of decimals.

   * When declaring columns using a `DECIMAL(length,dec)' type, the
     `length' argument no longer includes a place for the sign or the
     decimal point.

   * A `TIME' string must now be of one of the following formats:
     `[[[DAYS] [H]H:]MM:]SS[.fraction]' or
     `[[[[[H]H]H]H]MM]SS[.fraction]'.

   * `LIKE' now compares strings using the same character comparison
     rules as for the `=' operator.  If you require the old behavior,
     you can compile MySQL with the `CXXFLAGS=-DLIKE_CMP_TOUPPER' flag.

   * `REGEXP' now is case insensitive if neither of the strings is a
     binary string.

   * When you check or repair `MyISAM' (`.MYI') tables, you should use
     the `CHECK TABLE' statement or the `myisamchk' command. For `ISAM'
     (`.ISM') tables, use the `isamchk' command.

   * Check all your calls to `DATE_FORMAT()' to make sure that there is
     a `%' before each format character.  (MySQL 3.22 already allowed
     this syntax, but now `%' is required.)

   * In MySQL 3.22, the output of `SELECT DISTINCT ...' was almost
     always sorted.  In MySQL 3.23, you must use `GROUP BY' or `ORDER
     BY' to obtain sorted output.

   * `SUM()' now returns `NULL' instead of 0 if there are no matching
     rows. This is required by standard SQL.

   * An `AND' or `OR' with `NULL' values will now return `NULL' instead
     of 0. This mostly affects queries that use `NOT' on an `AND/OR'
     expression as `NOT NULL' = `NULL'.

   * `LPAD()' and `RPAD()' now shorten the result string if it's longer
     than the length argument.


*C API Changes:*

   * `mysql_fetch_fields_direct()' now is a function instead of a macro.
     It now returns a pointer to a `MYSQL_FIELD' instead of a
     `MYSQL_FIELD'.

   * `mysql_num_fields()' no longer can be used on a `MYSQL*' object
     (it's now a function that takes a `MYSQL_RES*' value as an
     argument). With a `MYSQL*' object, you now should use
     `mysql_field_count()' instead.


Upgrading from Version 3.21 to 3.22
-----------------------------------

Nothing that affects compatibility has changed between versions 3.21
and 3.22.  The only pitfall is that new tables that are created with
`DATE' type columns will use the new way to store the date. You can't
access these new columns from an old version of `mysqld'.

When upgrading to MySQL 3.23 from an earlier version, note the following
changes:

   * After installing MySQL Version 3.22, you should start the new
     server and then run the `mysql_fix_privilege_tables' script. This
     will add the new privileges that you need to use the `GRANT'
     command.  If you forget this, you will get `Access denied' when
     you try to use `ALTER TABLE', `CREATE INDEX', or `DROP INDEX'. The
     procedure for updating the grant tables is described in *Note
     Upgrading-grant-tables::.

   * The C API interface to `mysql_real_connect()' has changed.  If you
     have an old client program that calls this function, you must pass
     a `0' for the new `db' argument (or recode the client to send the
     `db' element for faster connections).  You must also call
     `mysql_init()' before calling `mysql_real_connect()'.  This change
     was done to allow the new `mysql_options()' function to save
     options in the `MYSQL' handler structure.

   * The `mysqld' variable `key_buffer' has been renamed to
     `key_buffer_size', but you can still use the old name in your
     startup files.


Upgrading from Version 3.20 to 3.21
-----------------------------------

If you are running a version older than Version 3.20.28 and want to
switch to Version 3.21, you need to do the following:

You can start the `mysqld' Version 3.21 server with the
`--old-protocol' option to use it with clients from a Version 3.20
distribution.  In this case, the server uses the old pre-3.21
`password()' checking rather than the new method. Also, the new client
function `mysql_errno()' will not return any server error, only
`CR_UNKNOWN_ERROR'. The function does work for client errors.

If you are _not_ using the `--old-protocol' option to `mysqld', you
will need to make the following changes:

   * All client code must be recompiled. If you are using ODBC, you
     must get the MyODBC 2.x driver.

   * The `scripts/add_long_password' script must be run to convert the
     `Password' field in the `mysql.user' table to `CHAR(16)'.

   * All passwords must be reassigned in the `mysql.user' table to get
     62-bit rather than 31-bit passwords.

   * The table format hasn't changed, so you don't have to convert any
     tables.


MySQL 3.20.28 and above can handle the new `user' table format without
affecting clients. If you have a MySQL version earlier than 3.20.28,
passwords will no longer work with it if you convert the `user' table.
So to be safe, you should first upgrade to at least Version 3.20.28 and
then upgrade to Version 3.21.

The new client code works with a 3.20.x `mysqld' server, so if you
experience problems with 3.21.x, you can use the old 3.20.x server
without having to recompile the clients again.

If you are not using the `--old-protocol' option to `mysqld', old
clients will be unable to connect and will issue the following error
message:

     ERROR: Protocol mismatch. Server Version = 10 Client Version = 9

The Perl DBI interface also supports the old `mysqlperl' interface.
The only change you have to make if you use `mysqlperl' is to change
the arguments to the `connect()' function.  The new arguments are:
`host', `database', `user', and `password' (note that the `user' and
`password' arguments have changed places).

The following changes may affect queries in old applications:

   * `HAVING' must now be specified before any `ORDER BY' clause.

   * The parameters to `LOCATE()' have been swapped.

   * There are some new reserved words. The most noticeable are `DATE',
     `TIME', and `TIMESTAMP'.


Upgrading MySQL Under Windows
-----------------------------

When upgrading MySQL under Windows, please follow these steps:

  1. Download the latest Windows distribution of MySQL.

  2. Choose a time of day with low usage, where a maintenance break is
     acceptable.

  3. Alert the users who still are active about the maintenance break.

  4. Stop the running MySQL Server (for example, with `NET STOP MySQL'
     or with the `Services' utility if you are running MySQL as a
     service, or with `mysqladmin shutdown' otherwise).

  5. Exit the `WinMySQLAdmin' program if it is running.

  6. Run the installation script of the Windows distribution by
     clicking the Install button in WinZip and following the
     installation steps of the script.

     *Important note:* Early alpha Windows distributions for MySQL 4.1
     do not contain an installer program.  See *Note Windows binary
     installation:: for instructions on how to install such a
     distribution.

  7. You may either overwrite your old MySQL installation (usually
     located at `C:\mysql'), or install it into a different directory,
     such as `C:\mysql4'. Overwriting the old installation is
     recommended.

  8. Restart the server. For example, use `NET START MySQL' if you run
     MySQL as a service, or invoke `mysqld' directly otherwise.

  9. Update the grant tables. The procedure is described in *Note
     Upgrading-grant-tables::.


Possible error situations:
     A system error has occurred.
     System error 1067 has occurred.
     The process terminated unexpectedly.

These errors mean that your option file (by default `C:\my.cnf')
contains an option that cannot be recognized by MySQL. You can verify
that this is the case by trying to restart MySQL with the option file
renamed to prevent the server from using it. (For example, rename
`C:\my.cnf' to `C:\my_cnf.old'.)  Once you have verified it, you need
to identify which option is the culprit. Create a new `my.cnf' file and
move parts of the old file to it (restarting the server after you move
each part) until you determine which option causes server startup to
fail.

Upgrading the Grant Tables
--------------------------

Some releases introduce changes to the structure of the grant tables
(the tables in the `mysql' database) to add new  privileges or
features. To make sure that your grant tables are current when you
update to a new version of MySQL, you should update your grant tables
as well.

On Unix or Unix-like systems, update the grant tables by running the
`mysql_fix_privilege_tables' script:

     shell> mysql_fix_privilege_tables

You must run this script while the server is running. It attempts to
connect to the server running on the local host as `root'.  If your
`root' account requires a password, indicate the password on the
command line.  For MySQL 4.1 and up, specify the password like this:

     shell> mysql_fix_privilege_tables --password=root_password

Prior to MySQL 4.1, specify the password like this:

     shell> mysql_fix_privilege_tables root_password

The `mysql_fix_privilege_tables' script performs any actions necessary
to convert your grant tables to the current format. You might see some
`Duplicate column name' warnings as it runs; you can ignore them.

After running the script, stop the server and restart it.

On Windows systems, there isn't an easy way to update the grant tables
until MySQL 4.0.15.  From version 4.0.15 on, MySQL distributions
include a `mysql_fix_privilege_tables.sql' SQL script that you can run
using the `mysql' client.  If your MySQL installation is located at
`C:\mysql', the commands look like this:

     C:\> C:\mysql\bin\mysql -u root -p mysql
     mysql> SOURCE C:\mysql\scripts\mysql_fix_privilege_tables.sql

If your installation is located in some other directory, adjust the
pathnames appropriately.

The `mysql' command will prompt you for the `root' password; enter it
when prompted.

As with the Unix procedure, you might see some `Duplicate column name'
warnings as `mysql' processes the statements in the
`mysql_fix_privilege_tables.sql' script; you can ignore them.

After running the script, stop the server and restart it.

If you are upgrading to MySQL 5.0.1 or later, the grant table upgrade
procedure just described will add view-related columns for the `CREATE
VIEW' and `SHOW VIEW' privileges.  These privileges exist at the global
and database levels. Their initial values are assigned as follows:

   * In MySQL 5.0.2 or later, `mysql_fix_privilege_tables' copies the
     `Create_priv' value in the `user' table to the `Create_view_priv'
     and `Show_view_priv' columns.

   * In 5.0.1, the view-related privileges are not enabled for any
     accounts, so you cannot immediately use `GRANT' to give them give
     them to accounts that should have them. To deal with this, first
     connect to the server as `root' and issue the following statements
     to give the privileges to the `root' accounts manually with
     `UPDATE':

          mysql> UPDATE mysql.user SET Show_view_priv = 'Y', Create_view_priv = 'Y'
              -> WHERE User = 'root';
          mysql> FLUSH PRIVILEGES;

     After this, `root' can use `GRANT' to give the view privileges to
     other accounts. Note: You should issue the statements just shown,
     `GRANT ALL' will not work at the global and database levels,
     because `GRANT ALL' requires that you actually possess all
     privileges.


Copying MySQL Databases to Another Machine
------------------------------------------

If you are using MySQL 3.23 or later, you can copy the `.frm', `.MYI',
and `.MYD' files for `MyISAM' tables between different architectures
that support the same floating-point format.  (MySQL takes care of any
byte-swapping issues.)  *Note `MyISAM' Tables: MyISAM.

The MySQL `ISAM' data and index files (`.ISD' and `*.ISM',
respectively) are architecture dependent and in some cases operating
system dependent.  If you want to move your applications to another
machine that has a different architecture or operating system than your
current machine, you should not try to move a database by simply copying
the files to the other machine. Use `mysqldump' instead.

By default, `mysqldump' will create a file containing SQL statements.
You can then transfer the file to the other machine and feed it as input
to the `mysql' client.

Try `mysqldump --help' to see what options are available.  If you are
moving the data to a newer version of MySQL, you should use `mysqldump
--opt' to take advantage of any optimizations that result in a dump
file that is smaller and can be processed faster.

The easiest (although not the fastest) way to move a database between
two machines is to run the following commands on the machine on which
the database is located:

     shell> mysqladmin -h 'OTHER_HOSTNAME' create DB_NAME
     shell> mysqldump --opt DB_NAME | mysql -h 'OTHER_HOSTNAME' DB_NAME

If you want to copy a database from a remote machine over a slow
network, you can use:

     shell> mysqladmin create DB_NAME
     shell> mysqldump -h 'OTHER_HOSTNAME' --opt --compress DB_NAME | mysql DB_NAME

You can also store the result in a file, then transfer the file to the
target machine and load the file into the database there.  For example,
you can dump a database to a file on the source machine like this:

     shell> mysqldump --quick DB_NAME | gzip > DB_NAME.CONTENTS.gz

(The file created in this example is compressed.) Transfer the file
containing the database contents to the target machine and run these
commands there:

     shell> mysqladmin create DB_NAME
     shell> gunzip < DB_NAME.CONTENTS.gz | mysql DB_NAME

You can also use `mysqldump' and `mysqlimport' to transfer the database.
For big tables, this is much faster than simply using `mysqldump'.  In
the following commands, `DUMPDIR' represents the full pathname of the
directory you use to store the output from `mysqldump'.

First, create the directory for the output files and dump the database:

     shell> mkdir DUMPDIR
     shell> mysqldump --tab=DUMPDIR DB_NAME

Then transfer the files in the `DUMPDIR' directory to some corresponding
directory on the target machine and load the files into MySQL there:

     shell> mysqladmin create DB_NAME           # create database
     shell> cat DUMPDIR/*.sql | mysql DB_NAME   # create tables in database
     shell> mysqlimport DB_NAME DUMPDIR/*.txt   # load data into tables

Also, don't forget to copy the `mysql' database because that is where
the `user', `db', and `host' grant tables are stored.  You might have
to run commands as the MySQL `root' user on the new machine until you
have the `mysql' database in place.

After you import the `mysql' database on the new machine, execute
`mysqladmin flush-privileges' so that the server reloads the grant table
information.

Operating System-Specific Notes
===============================

Linux Notes
-----------

This section discusses issues that have been found to occur on Linux.
The first few subsections describe general operating system-related
issues, problems that can occur when using binary or source
distributions, and post-installation issues. The remaining subsections
discuss problems that occur with Linux on specific platforms.

Note that most of these problems occur on older versions of Linux. If
you are running a recent version, you likely will see none of them.

Linux Operating System Notes
............................

MySQL needs at least Linux Version 2.0.

*Warning:* We have seen some strange problems with Linux 2.2.14 and
MySQL on SMP systems.  We also have reports from some MySQL users that
they have encountered serious stability problems using MySQL with
kernel 2.2.14.  If you are using this kernel, you should upgrade to
2.2.19 (or newer) or to a 2.4 kernel.  If you have a multiple-CPU box,
then you should seriously consider using 2.4 because it will give you a
significant speed boost.  Your system also will be more stable.

When using LinuxThreads, you will see a minimum of three `mysqld'
processes running.  These are in fact threads.  There will be one
thread for the LinuxThreads manager, one thread to handle connections,
and one thread to handle alarms and signals.

Linux Binary Distribution Notes
...............................

The Linux-Intel binary and RPM releases of MySQL are configured for the
highest possible speed.  We are always trying to use the fastest stable
compiler available.

The binary release is linked with `-static', which means you do not
normally need to worry about which version of the system libraries you
have. You need not install LinuxThreads, either.  A program linked with
`-static' is slightly larger than a dynamically linked program, but
also slightly faster (3-5%).  However, one problem with a statically
linked program is that you can't use user-defined functions (UDFs).  If
you are going to write or use UDFs (this is something for C or C++
programmers only), you must compile MySQL yourself using dynamic
linking.

A known issue with binary distributions is that on older Linux systems
that use `libc' (such as Red Hat 4.x or Slackware), you will get some
non-fatal problems with hostname resolution. If your system uses `libc'
rather than `glibc2', you probably will encounter some difficulties
with hostname resolution and `getpwnam()'. This happens because `glibc'
unfortunately depends on some external libraries to implement hostname
resolution and `getpwent()', even when compiled with `-static'.  These
problems manifest themselves in two ways:

   * You probably will see  the following error message when you run
     `mysql_install_db':

          Sorry, the host 'XXXX' could not be looked up

     You can deal with this by executing `mysql_install_db --force',
     which will not execute the `resolveip' test in `mysql_install_db'.
     The downside is that you can't use hostnames in the grant tables:
     Except for `localhost', you must use IP numbers instead.  If you
     are using an old version of MySQL that doesn't support `--force',
     you must manually remove the `resolveip' test in `mysql_install'
     using an editor.

   * You also may see the following error when you try to run `mysqld'
     with the `--user' option:

          getpwnam: No such file or directory

     To work around this, start `mysqld' by using the `su' command
     rather than by specifying the `--user' option. This causes the
     system itself to change the user ID of the `mysqld' process so
     that `mysqld' need not do so.


Another solution, which solves both problems, is to not use a binary
distribution.  Get a MySQL source distribution (in RPM or `tar.gz'
format) and install that instead.

On some Linux 2.2 versions, you may get the error `Resource temporarily
unavailable' when clients make a lot of new connections to a `mysqld'
server over TCP/IP.  The problem is that Linux has a delay between the
time that you close a TCP/IP socket and the time that the system
actually frees it.  There is room for only a finite number of TCP/IP
slots, so you will encounter the resource-unavailable error if clients
attempt too many new TCP/IP connections during a short time. For
example, you may see the error when you run the MySQL `test-connect'
benchmark over TCP/IP.

We have inquired about this problem a few times on different Linux
mailing lists but have never been able to find a suitable resolution.
The only known "fix" is for the clients to use persistent connections,
or, if you are running the database server and clients on the same
machine, to use Unix socket file connections rather than TCP/IP
connections.

Linux Source Distribution Notes
...............................

The following notes regarding `glibc' apply only to the situation when
you build MySQL yourself. If you are running Linux on an x86 machine,
in most cases it is much better for you to just use our binary. We link
our binaries against the best patched version of `glibc' we can come up
with and with the best compiler options, in an attempt to make it
suitable for a high-load server.  For a typical user, even for setups
with a lot of concurrent connections or tables exceeding the 2GB limit,
our binary is the best choice in most cases.  After reading the
following text, if you are in doubt about what to do, try our binary
first to see whether it meets your needs.  If you discover that it is
not good enough, then you may want to try your own build.  In that
case, we would appreciate a note about it so that we can build a better
binary next time.

MySQL uses LinuxThreads on Linux.  If you are using an old Linux
version that doesn't have `glibc2', you must install LinuxThreads
before trying to compile MySQL.   You can get LinuxThreads at
`http://dev.mysql.com/downloads/os-linux.html'.

Note that `glibc' versions before and including Version 2.1.1 have a
fatal bug in `pthread_mutex_timedwait()' handling, which is used when
you issue `INSERT DELAYED' statements.  We recommend that you not use
`INSERT DELAYED' before upgrading `glibc'.

Note that Linux kernel and the LinuxThread library can by default only
have 1,024 threads.  If you plan to have more than 1,000 concurrent
connections, you will need to make some changes to LinuxThreads:

   * Increase `PTHREAD_THREADS_MAX' in
     `sysdeps/unix/sysv/linux/bits/local_lim.h' to 4096 and decrease
     `STACK_SIZE' in `linuxthreads/internals.h' to 256KB. The paths are
     relative to the root of `glibc'. (Note that MySQL will not be
     stable with around 600-1000 connections if `STACK_SIZE' is the
     default of 2MB.)

   * Recompile LinuxThreads to produce a new `libpthread.a' library,
     and relink MySQL against it.


The page `http://www.volano.com/linuxnotes.html' contains additional
information about circumventing thread limits in LinuxThreads.

There is another issue that greatly hurts MySQL performance, especially
on SMP systems.  The mutex implementation in LinuxThreads in `glibc'
2.1 is very bad for programs with many threads that hold the mutex only
for a short time.  This produces a paradoxical result: If you link
MySQL against an unmodified LinuxThreads, removing processors from an
SMP actually improves MySQL performance in many cases.  We have made a
patch available for `glibc' 2.1.3 to correct this behavior
(`http://www.mysql.com/Downloads/Linux/linuxthreads-2.1-patch').

With `glibc' 2.2.2, MySQL 3.23.36 will use the adaptive mutex, which is
much better than even the patched one in `glibc' 2.1.3. Be warned,
however, that under some conditions, the current mutex code in `glibc'
2.2.2 overspins, which hurts MySQL performance. The likelihood that
this condition will occur can be reduced by renicing the `mysqld'
process to the highest priority. We have also been able to correct the
overspin behavior with a patch, available at
`http://www.mysql.com/Downloads/Linux/linuxthreads-2.2.2.patch'.  It
combines the correction of overspin, maximum number of threads, and
stack spacing all in one. You will need to apply it in the
`linuxthreads' directory with `patch -p0
</tmp/linuxthreads-2.2.2.patch'.  We hope it will be included in some
form in future releases of `glibc' 2.2. In any case, if you link
against `glibc' 2.2.2, you still need to correct `STACK_SIZE' and
`PTHREAD_THREADS_MAX'. We hope that the defaults will be corrected to
some more acceptable values for high-load MySQL setup in the future, so
that the commands needed to produce your own build can be reduced to
`./configure; make; make install'.

We recommend that you use these patches to build a special static
version of `libpthread.a' and use it only for statically linking
against MySQL. We know that the patches are safe for MySQL and
significantly improve its performance, but we cannot say anything about
other applications. If you link other applications that require
LinuxThreads against the patched static version of the library, or
build a patched shared version and install it on your system, you do so
at your own risk.

If you experience any strange problems during the installation of
MySQL, or with some common utilities hanging, it is very likely that
they are either library or compiler related. If this is the case, using
our binary will resolve them.

If you link your own MySQL client programs, you may see the following
error at runtime:

     ld.so.1: fatal: libmysqlclient.so.#:
     open failed: No such file or directory

This problem can be avoided by one of the following methods:

   * Link clients with the `-Wl,r/full/path/to/libmysqlclient.so' flag
     rather than with `-Lpath').

   * Copy `libmysqclient.so' to `/usr/lib'.

   * Add the pathname of the directory where `libmysqlclient.so' is
     located to the `LD_RUN_PATH' environment variable before running
     your client.

If you are using the Fujitsu compiler (`fcc/FCC'), you will have some
problems compiling MySQL because the Linux header files are very `gcc'
oriented.  The following `configure' line should work with `fcc/FCC':

     CC=fcc CFLAGS="-O -K fast -K lib -K omitfp -Kpreex -D_GNU_SOURCE \
         -DCONST=const -DNO_STRTOLL_PROTO" \
     CXX=FCC CXXFLAGS="-O -K fast -K lib \
         -K omitfp -K preex --no_exceptions --no_rtti -D_GNU_SOURCE \
         -DCONST=const -Dalloca=__builtin_alloca -DNO_STRTOLL_PROTO \
         '-D_EXTERN_INLINE=static __inline'" \
     ./configure \
         --prefix=/usr/local/mysql --enable-assembler \
         --with-mysqld-ldflags=-all-static --disable-shared \
         --with-low-memory

Linux Post-Installation Notes
.............................

`mysql.server' can be found in the `support-files' directory under the
MySQL installation directory or in a MySQL source tree.  You can install
it as `/etc/init.d/mysql' for automatic MySQL startup and shutdown.
*Note Automatic start::.

If MySQL can't open enough files or connections, it may be that you
haven't configured Linux to handle enough files.

In Linux 2.2 and onward, you can check the number of allocated file
handles as follows:

     shell> cat /proc/sys/fs/file-max
     shell> cat /proc/sys/fs/dquot-max
     shell> cat /proc/sys/fs/super-max

If you have more than 16MB of memory, you should add something like the
following to your init scripts (for example, `/etc/init.d/boot.local'
on SuSE Linux):

     echo 65536 > /proc/sys/fs/file-max
     echo 8192 > /proc/sys/fs/dquot-max
     echo 1024 > /proc/sys/fs/super-max

You can also run the `echo' commands from the command line as `root',
but these settings will be lost the next time your computer restarts.

Alternatively, you can set these parameters on startup by using the
`sysctl' tool, which is used by many Linux distributions (SuSE has
added it as well, beginning with SuSE Linux 8.0). Just put the following
values into a file named `/etc/sysctl.conf':

     # Increase some values for MySQL
     fs.file-max = 65536
     fs.dquot-max = 8192
     fs.super-max = 1024

You should also add the following to `/etc/my.cnf':

     [mysqld_safe]
     open-files-limit=8192

This should allow the server a limit of 8,192 for the combined number of
connections and open files.

The `STACK_SIZE' constant in LinuxThreads controls the spacing of thread
stacks in the address space.  It needs to be large enough so that there
will be plenty of room for each individual thread stack, but small
enough to keep the stack of some threads from running into the global
`mysqld' data.  Unfortunately, as we have experimentally discovered,
the Linux implementation of `mmap()' will successfully unmap an already
mapped region if you ask it to map out an address already in use,
zeroing out the data on the entire page instead of returning an error.
So, the safety of `mysqld' or any other threaded application depends on
"gentlemanly" behavior of the code that creates threads.  The user must
take measures to make sure that the number of running threads at any
time is sufficiently low for thread stacks to stay away from the global
heap.  With `mysqld', you should enforce this behavior by setting a
reasonable value for the `max_connections' variable.

If you build MySQL yourself, you can patch LinuxThreads for better
stack use.  *Note Source notes-Linux::.  If you do not want to patch
LinuxThreads, you should set `max_connections' to a value no higher
than 500.  It should be even less if you have a large key buffer,  large
heap tables, or some other things that make `mysqld' allocate a lot of
memory, or if you are running a 2.2 kernel with a 2GB patch. If you are
using our binary or RPM version 3.23.25 or later, you can safely set
`max_connections' at 1500, assuming no large key buffer or heap tables
with lots of data.  The more you reduce `STACK_SIZE' in LinuxThreads
the more threads you can safely create.  We recommend values between
128KB and 256KB.

If you use a lot of concurrent connections, you may suffer from a
"feature" in the 2.2 kernel that attempts to prevent fork bomb attacks
by penalizing a process for forking or cloning a child.  This causes
MySQL not to scale well as you increase the number of concurrent
clients.  On single-CPU systems, we have seen this manifested as very
slow thread creation: It may take a long time to connect to MySQL (as
long as one minute), and it may take just as long to shut it down.  On
multiple-CPU systems, we have observed a gradual drop in query speed as
the number of clients increases.  In the process of trying to find a
solution, we have received a kernel patch from one of our users who
claimed it made a lot of difference for his site.  The patch is
available at `http://www.mysql.com/Downloads/Patches/linux-fork.patch'.
We have now done rather extensive testing of this patch on both
development and production systems.  It has significantly improved
MySQL performance without causing any problems and we now recommend it
to our users who still run high-load servers on 2.2 kernels.

This issue has been fixed in the 2.4 kernel, so if you are not satisfied
with the current performance of your system, rather than patching your
2.2 kernel, it might be easier to upgrade to 2.4. On SMP systems,
upgrading also will give you a nice SMP boost in addition to fixing the
fairness bug.

We have tested MySQL on the 2.4 kernel on a two-CPU machine and found
MySQL scales _much_ better. There was virtually no slowdown on query
throughput all the way up to 1,000 clients, and the MySQL scaling factor
(computed as the ratio of maximum throughput to the throughput for one
client) was 180%.  We have observed similar results on a four-CPU
system: Virtually no slowdown as the number of clients was increased up
to 1,000, and a 300% scaling factor. Based on these results, for a
high-load SMP server using a 2.2 kernel, we definitely recommend
upgrading to the 2.4 kernel at this point.

We have discovered that it is essential to run the `mysqld' process
with the highest possible priority on the 2.4 kernel to achieve maximum
performance.  This can be done by adding a `renice -20 $$' command to
`mysqld_safe'. In our testing on a four-CPU machine, increasing the
priority resulted in a 60% throughput increase with 400 clients.

We are currently also trying to collect more information on how well
MySQL performs with a 2.4 kernel on four-way and eight-way systems. If
you have access such a system and have done some benchmarks, please
send an email message to <[e-mail]> with the results. We
will review them for inclusion in the manual.

If you see a dead `mysqld' server process with `ps', this usually means
that you have found a bug in MySQL or you have a corrupted table. *Note
Crashing::.

To get a core dump on Linux if `mysqld' dies with a `SIGSEGV' signal,
you can start `mysqld' with the `--core-file' option.  Note that you
also probably need to raise the core file size by adding `ulimit -c
1000000' to `mysqld_safe' or starting `mysqld_safe' with
`--core-file-size=1000000'.  *Note `mysqld_safe': mysqld_safe.

Linux x86 Notes
...............

MySQL requires `libc' Version 5.4.12 or newer. It's known to work with
`libc' 5.4.46.  `glibc' Version 2.0.6 and later should also work. There
have been some problems with the `glibc' RPMs from Red Hat, so if you
have problems, check whether there are any updates.  The `glibc'
2.0.7-19 and 2.0.7-29 RPMs are known to work.

If you are using Red Hat 8.0 or a new `glibc' 2.2.x library, you may see
`mysqld' die in `gethostbyaddr()'. This happens because the new `glibc'
library requires a stack size greater than 128KB for this call.  To fix
the problem, start `mysqld' with the `--thread-stack=192K' option.
(Use `-O thread_stack=192K' before MySQL 4.)  This stack size is now
the default on MySQL 4.0.10 and above, so you should not see the
problem.

If you are using `gcc' 3.0 and above to compile MySQL, you must install
the `libstdc++v3' library before compiling MySQL; if you don't do this,
you will get an error about a missing `__cxa_pure_virtual' symbol
during linking.

On some older Linux distributions, `configure' may produce an error
like this:

     Syntax error in sched.h. Change _P to __P in the
     /usr/include/sched.h file.
     See the Installation chapter in the Reference Manual.

Just do what the error message says. Add an extra underscore to the
`_P' macro name that has only one underscore, then try again.

You may get some warnings when compiling. Those shown here can be
ignored:

     mysqld.cc -o objs-thread/mysqld.o
     mysqld.cc: In function `void init_signals()':
     mysqld.cc:315: warning: assignment of negative value `-1' to
     `long unsigned int'
     mysqld.cc: In function `void * signal_hand(void *)':
     mysqld.cc:346: warning: assignment of negative value `-1' to
     `long unsigned int'

If `mysqld' always dumps core when it starts, the problem may be that
you have an old `/lib/libc.a'.  Try renaming it, then remove
`sql/mysqld' and do a new `make install' and try again.  This problem
has been reported on some Slackware installations.

If you get the following error when linking `mysqld', it means that
your `libg++.a' is not installed correctly:

     /usr/lib/libc.a(putc.o): In function `_IO_putc':
     putc.o(.text+0x0): multiple definition of `_IO_putc'

You can avoid using `libg++.a' by running `configure' like this:

     shell> CXX=gcc ./configure

If `mysqld' crashes immediately and you are running Red Hat Version 5.0
with a version of `glibc' older than 2.0.7-5, you should make sure that
you have installed all `glibc' patches.  There is a lot of information
about this in the MySQL mail archives, available online at
`http://lists.mysql.com/'.

Linux SPARC Notes
.................

In some implementations, `readdir_r()' is broken.  The symptom is that
the `SHOW DATABASES' statement always returns an empty set.  This can
be fixed by removing `HAVE_READDIR_R' from `config.h' after configuring
and before compiling.

Linux Alpha Notes
.................

MySQL 3.23.12 is the first MySQL version that is tested on Linux-Alpha.
If you plan to use MySQL on Linux-Alpha, you should ensure that you
have this version or newer.

We have tested MySQL on Alpha with our benchmarks and test suite, and
it appears to work nicely.

We currently build the MySQL binary packages on SuSE Linux 7.0 for AXP,
kernel 2.4.4-SMP, Compaq C compiler (V6.2-505) and Compaq C++ compiler
(V6.3-006) on a Compaq DS20 machine with an Alpha EV6 processor.

You can find the preceding compilers at
`http://www.support.compaq.com/alpha-tools/'.  By using these compilers
rather than `gcc', we get about 9-14% better MySQL performance.

Note that until MySQL version 3.23.52 and 4.0.2, we optimized the
binary for the current CPU only (by using the `-fast' compile option).
This means that for older versions, you can use our Alpha binaries only
if you have an Alpha EV6 processor.

For all following releases, we added the `-arch generic' flag to our
compile options, which makes sure that the binary runs on all Alpha
processors. We also compile statically to avoid library problems.  The
`configure' command looks like this:

     CC=ccc CFLAGS="-fast -arch generic" CXX=cxx \
     CXXFLAGS="-fast -arch generic -noexceptions -nortti" \
     ./configure --prefix=/usr/local/mysql --disable-shared \
         --with-extra-charsets=complex --enable-thread-safe-client \
         --with-mysqld-ldflags=-non_shared --with-client-ldflags=-non_shared

If you want to use `egcs', the following `configure' line worked for us:

     CFLAGS="-O3 -fomit-frame-pointer" CXX=gcc \
     CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors \
         -fno-exceptions -fno-rtti" \
     ./configure --prefix=/usr/local/mysql --disable-shared

Some known problems when running MySQL on Linux-Alpha:

   * Debugging threaded applications like MySQL will not work with `gdb
     4.18'.  You should use `gdb' 5.1 instead.

   * If you try linking `mysqld' statically when using `gcc', the
     resulting image will dump core at startup time.  In other words,
     _do not_ use `--with-mysqld-ldflags=-all-static' with `gcc'.

Linux PowerPC Notes
...................

MySQL should work on MkLinux with the newest `glibc' package (tested
with `glibc' 2.0.7).

Linux MIPS Notes
................

To get MySQL to work on Qube2 (Linux Mips), you need the newest `glibc'
libraries. `glibc-2.0.7-29C2' is known to work.  You must also use the
`egcs' C++ compiler (`egcs' 1.0.2-9, `gcc' 2.95.2 or newer).

Linux IA-64 Notes
.................

To get MySQL to compile on Linux IA-64, we use the following `configure'
command for building with `gcc' 2.96:

     CC=gcc \
     CFLAGS="-O3 -fno-omit-frame-pointer" \
     CXX=gcc \
     CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors \
         -fno-exceptions -fno-rtti" \
         ./configure --prefix=/usr/local/mysql \
         "--with-comment=Official MySQL binary" \
         --with-extra-charsets=complex

On IA-64, the MySQL client binaries use shared libraries. This means
that if you install our binary distribution at a location other than
`/usr/local/mysql', you need to add the path of the directory where you
have `libmysqlclient.so' installed either to the `/etc/ld.so.conf' file
or to the value of your `LD_LIBRARY_PATH' environment variable.

*Note Link errors::.

Mac OS X Notes
--------------

On Mac OS X, `tar' cannot handle long filenames. If you need to unpack a
`.tar.gz' distribution, use `gnutar' instead.

Mac OS X 10.x (Darwin)
......................

MySQL should work without any problems on Mac OS X 10.x (Darwin).

Our binary for Mac OS X is compiled on Darwin 6.3 with the following
`configure' line:

     CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc \
     CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors \
         -fno-exceptions -fno-rtti" \
         ./configure --prefix=/usr/local/mysql \
         --with-extra-charsets=complex --enable-thread-safe-client \
         --enable-local-infile --disable-shared

*Note Mac OS X installation::.

Mac OS X Server 1.2 (Rhapsody)
..............................

For current versions of Mac OS X Server, no operating system changes are
necessary before compiling MySQL.  Compiling for the Server platform is
the same as for the client version of Mac OS X. (However, note that
MySQL comes preinstalled on Mac OS X Server, so you need not build it
yourself.)

For older versions (Mac OS X Server 1.2, a.k.a. Rhapsody), you must
first install a pthread package before trying to configure MySQL.

*Note Mac OS X installation::.

Solaris Notes
-------------

On Solaris, you may run into trouble even before you get the MySQL
distribution unpacked!  Solaris `tar' can't handle long filenames, so
you may see an error like this when you unpack MySQL:

     x mysql-3.22.12-beta/bench/Results/ATIS-mysql_odbc-NT_4.0-cmp-db2,
     informix,ms-sql,mysql,oracle,solid,sybase, 0 bytes, 0 tape blocks
     tar: directory checksum error

In this case, you must use GNU `tar' (`gtar') to unpack the
distribution.  You can find a precompiled copy for Solaris at
`http://dev.mysql.com/downloads/os-solaris.html'.

Sun native threads work only on Solaris 2.5 and higher.  For Version
2.4 and earlier, MySQL automatically uses MIT-pthreads.  *Note
MIT-pthreads::.

If you get the following error from `configure', it means that you have
something wrong with your compiler installation:

     checking for restartable system calls... configure: error can not
     run test programs while cross compiling

In this case, you should upgrade your compiler to a newer version.  You
may also be able to solve this problem by inserting the following row
into the `config.cache' file:

     ac_cv_sys_restartable_syscalls=${ac_cv_sys_restartable_syscalls='no'}

If you are using Solaris on a SPARC, the recommended compiler is `gcc'
2.95.2 or 3.2. You can find this at `http://gcc.gnu.org/'.  Note that
`egcs' 1.1.1 and `gcc' 2.8.1 don't work reliably on SPARC!

The recommended `configure' line when using `gcc' 2.95.2 is:

     CC=gcc CFLAGS="-O3" \
     CXX=gcc CXXFLAGS="-O3 -felide-constructors -fno-exceptions -fno-rtti" \
     ./configure --prefix=/usr/local/mysql --with-low-memory \
         --enable-assembler

If you have an UltraSPARC system, you can get 4% better performance by
adding `-mcpu=v8 -Wa,-xarch=v8plusa' to the `CFLAGS' and `CXXFLAGS'
environment variables.

If you have Sun's Forte 5.0 (or newer) compiler, you can run
`configure' like this:

     CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt" \
     CXX=CC CXXFLAGS="-noex -mt" \
     ./configure --prefix=/usr/local/mysql --enable-assembler

To create a 64-bit binary with Sun's Forte compiler, use the following
configuration options:

     CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt -xarch=v9" \
     CXX=CC CXXFLAGS="-noex -mt -xarch=v9" ASFLAGS="-xarch=v9" \
     ./configure --prefix=/usr/local/mysql --enable-assembler

To create a 64-bit Solaris binary using `gcc', add `-m64' to `CFLAGS'
and `CXXFLAGS' and remove `--enable-assembler' from the `configure'
line. This works only with MySQL 4.0 and up; MySQL 3.23 does not
include the required modifications to support this.

In the MySQL benchmarks, we got a 4% speedup on an UltraSPARC when using
Forte 5.0 in 32-bit mode compared to using `gcc' 3.2 with the `-mcpu'
flag.

If you create a 64-bit `mysqld' binary, it is 4% slower than the 32-bit
binary, but can handle more threads and memory.

If you get a problem with `fdatasync' or `sched_yield', you can fix
this by adding `LIBS=-lrt' to the `configure' line

For compilers older than WorkShop 5.3, you might have to edit the
`configure' script. Change this line:

     #if !defined(__STDC__) || __STDC__ != 1

To this:

     #if !defined(__STDC__)

If you turn on `__STDC__' with the `-Xc' option, the Sun compiler can't
compile with the Solaris `pthread.h' header file.  This is a Sun bug
(broken compiler or broken include file).

If `mysqld' issues the following error message when you run it, you have
tried to compile MySQL with the Sun compiler without enabling the `-mt'
multi-thread option:

     libc internal error: _rmutex_unlock: rmutex not held

Add `-mt' to `CFLAGS' and `CXXFLAGS' and recompile.

If you are using the SFW version of `gcc' (which comes with Solaris 8),
you must add `/opt/sfw/lib' to the environment variable
`LD_LIBRARY_PATH' before running `configure'.

If you are using the `gcc' available from `sunfreeware.com', you may
have many problems.  To avoid this, you should recompile `gcc' and GNU
`binutils' on the machine where you will be running them.

If you get the following error when compiling MySQL with `gcc', it
means that your `gcc' is not configured for your version of Solaris:

     shell> gcc -O3 -g -O2 -DDBUG_OFF  -o thr_alarm ...
     ./thr_alarm.c: In function `signal_hand':
     ./thr_alarm.c:556: too many arguments to function `sigwait'

The proper thing to do in this case is to get the newest version of
`gcc' and compile it with your current `gcc' compiler.  At least for
Solaris 2.5, almost all binary versions of `gcc' have old, unusable
include files that will break all programs that use threads, and
possibly other programs!

Solaris doesn't provide static versions of all system libraries
(`libpthreads' and `libdl'), so you can't compile MySQL with
`--static'.  If you try to do so, you will get one of the following
errors:

     ld: fatal: library -ldl: not found
     undefined reference to `dlopen'
     cannot find -lrt

If you link your own MySQL client programs, you may see the following
error at runtime:

     ld.so.1: fatal: libmysqlclient.so.#:
     open failed: No such file or directory

This problem can be avoided by one of the following methods:

   * Link clients with the `-Wl,r/full/path/to/libmysqlclient.so' flag
     rather than with `-Lpath').

   * Copy `libmysqclient.so' to `/usr/lib'.

   * Add the pathname of the directory where `libmysqlclient.so' is
     located to the `LD_RUN_PATH' environment variable before running
     your client.

If you have problems with `configure' trying to link with `-lz' when
you don't have `zlib' installed, you have two options:

   * If you want to be able to use the compressed communication
     protocol, you need to get and install `zlib' from `ftp.gnu.org'.

   * Run `configure' with the `--with-named-z-libs=no' option when
     building MySQL.

If you are using `gcc' and have problems with loading user-defined
functions (UDFs) into MySQL, try adding `-lgcc' to the link line for
the UDF.

If you would like MySQL to start automatically, you can copy
`support-files/mysql.server' to `/etc/init.d' and create a symbolic
link to it named `/etc/rc3.d/S99mysql.server'.

If too many processes try to connect very rapidly to `mysqld', you will
see this error in the MySQL log:

     Error in accept: Protocol error

You might try starting the server with the `--back_log=50' option as a
workaround for this.  (Use `-O back_log=50' before MySQL 4.)

Solaris doesn't support core files for `setuid()' applications, so you
can't get a core file from `mysqld' if you are using the `--user'
option.

Solaris 2.7/2.8 Notes
.....................

Normally, you can use a Solaris 2.6 binary on Solaris 2.7 and 2.8.  Most
of the Solaris 2.6 issues also apply for Solaris 2.7 and 2.8.

MySQL 3.23.4 and above should be able to detect new versions of Solaris
automatically and enable workarounds for the following problems.

Solaris 2.7 / 2.8 has some bugs in the include files.  You may see the
following error when you use `gcc':

     /usr/include/widec.h:42: warning: `getwc' redefined
     /usr/include/wchar.h:326: warning: this is the location of the previous
     definition

If this occurs, you can fix the problem by copying
`/usr/include/widec.h' to `.../lib/gcc-lib/os/gcc-version/include' and
changing line 41 from this:

     #if     !defined(lint) && !defined(__lint)

To this:

     #if     !defined(lint) && !defined(__lint) && !defined(getwc)

Alternatively, you can edit `/usr/include/widec.h' directly.  Either
way, after you make the fix, you should remove `config.cache' and run
`configure' again.

If you get the following errors when you run `make', it's because
`configure' didn't detect the `curses.h' file (probably because of the
error in `/usr/include/widec.h'):

     In file included from mysql.cc:50:
     /usr/include/term.h:1060: syntax error before `,'
     /usr/include/term.h:1081: syntax error before `;'

The solution to this problem is to do one of the following:

   * Configure with `CFLAGS=-DHAVE_CURSES_H CXXFLAGS=-DHAVE_CURSES_H
     ./configure'.

   * Edit `/usr/include/widec.h' as indicated in the preceding
     discussion and re-run `configure'.

   * Remove the `#define HAVE_TERM' line from the `config.h' file and
     run `make' again.

If your linker can't find `-lz' when linking client programs, the
problem is probably that your `libz.so' file is installed in
`/usr/local/lib'.  You can fix this problem by one of the following
methods:

   * Add `/usr/local/lib' to `LD_LIBRARY_PATH'.

   * Add a link to `libz.so' from `/lib'.

   * If you are using Solaris 8, you can install the optional `zlib'
     from your Solaris 8 CD distribution.

   * Run `configure' with the `--with-named-z-libs=no' option when
     building MySQL.

Solaris x86 Notes
.................

On Solaris 8 on x86, `mysqld' will dump core if you remove the debug
symbols using `strip'.

If you are using `gcc' or `egcs' on Solaris x86 and you experience
problems with core dumps under load, you should use the following
`configure' command:

     CC=gcc CFLAGS="-O3 -fomit-frame-pointer -DHAVE_CURSES_H" \
     CXX=gcc \
     CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors \
         -fno-exceptions -fno-rtti -DHAVE_CURSES_H" \
     ./configure --prefix=/usr/local/mysql

This will avoid problems with the `libstdc++' library and with C++
exceptions.

If this doesn't help, you should compile a debug version and run it
with a trace file or under `gdb'.  *Note Using `gdb' on `mysqld': Using
gdb on mysqld.

BSD Notes
---------

This section provides information about using MySQL on variants of BSD
Unix.

FreeBSD Notes
.............

FreeBSD 4.x or newer is recommended for running MySQL, because the
thread package is much more integrated.  To get a secure and stable
system, you should use only FreeBSD kernels that are marked `-RELEASE'.

The easiest (and preferred) way to install MySQL is to use the
`mysql-server' and `mysql-client' ports available at
`http://www.freebsd.org/'.  Using these ports gives you the following
benefits:

   * A working MySQL with all optimizations enabled that are known to
     work on your version of FreeBSD.

   * Automatic configuration and build.

   * Startup scripts installed in `/usr/local/etc/rc.d'.

   * The ability to use `pkg_info -L' to see which files are installed.

   * The ability to use `pkg_delete' to remove MySQL if you no longer
     want it on your machine.

It is recommended you use MIT-pthreads on FreeBSD 2.x, and native
threads on Versions 3 and up. It is possible to run with native threads
on some late 2.2.x versions, but you may encounter problems shutting
down `mysqld'.

Unfortunately, certain function calls on FreeBSD are not yet fully
thread-safe.  Most notably, this includes the `gethostbyname()'
function, which is used by MySQL to convert hostnames into IP
addresses. Under certain circumstances, the `mysqld' process will
suddenly cause 100% CPU load and will be unresponsive. If you encounter
this problem, try to start MySQL using the `--skip-name-resolve' option.

Alternatively, you can link MySQL on FreeBSD 4.x against the
LinuxThreads library, which avoids a few of the problems that the
native FreeBSD thread implementation has. For a very good comparison of
LinuxThreads versus native threads, see Jeremy Zawodny's article
`FreeBSD or Linux for your MySQL Server?' at
`http://jeremy.zawodny.com/blog/archives/000697.html'.

A known problem when using LinuxThreads on FreeBSD is that the
`wait_timeout' value is not honored (probably a signal handling problem
in FreeBSD/LinuxThreads).  This is supposed to be fixed in FreeBSD 5.0.
The symptom is that persistent connections can hang for a very long
time without getting closed down.

The MySQL build process requires GNU make (`gmake') to work.  If GNU
`make' is not available, you must install it first before compiling
MySQL.

The recommended way to compile and install MySQL on FreeBSD with `gcc'
(2.95.2 and up) is:

     CC=gcc CFLAGS="-O2 -fno-strength-reduce" \
         CXX=gcc CXXFLAGS="-O2 -fno-rtti -fno-exceptions \
         -felide-constructors -fno-strength-reduce" \
         ./configure --prefix=/usr/local/mysql --enable-assembler
     gmake
     gmake install
     cd /usr/local/mysql
     bin/mysql_install_db --user=mysql
     bin/mysqld_safe &

If you notice that `configure' will use MIT-pthreads, you should read
the MIT-pthreads notes.  *Note MIT-pthreads::.

If you get an error from `make install' that it can't find
`/usr/include/pthreads', `configure' didn't detect that you need
MIT-pthreads. To fix this problem, remove `config.cache', then re-run
`configure' with the `--with-mit-threads' option.

Be sure that your name resolver setup is correct.  Otherwise, you may
experience resolver delays or failures when connecting to `mysqld'.
Also make sure that the `localhost' entry in the `/etc/hosts' file is
correct.  The file should start with a line similar to this:

     127.0.0.1       localhost localhost.your.domain

FreeBSD is known to have a very low default file handle limit.  *Note
Not enough file handles::.  Start the server by using the
`--open-files-limit' option for `mysqld_safe', or raise the limits for
the `mysqld' user in `/etc/login.conf' and rebuild it with `cap_mkdb
/etc/login.conf'.  Also be sure that you set the appropriate class for
this user in the password file if you are not using the default (use
`chpass mysqld-user-name').  *Note `mysqld_safe': mysqld_safe.

If you have a lot of memory, you should consider rebuilding the kernel
to allow MySQL to use more than 512MB of RAM.  Take a look at `option
MAXDSIZ' in the LINT config file for more information.

If you get problems with the current date in MySQL, setting the `TZ'
variable will probably help.  *Note Environment variables::.

NetBSD Notes
............

To compile on NetBSD, you need GNU `make'. Otherwise, the build process
will fail when `make' tries to run `lint' on C++ files.

OpenBSD 2.5 Notes
.................

On OpenBSD Version 2.5, you can compile MySQL with native threads with
the following options:

     CFLAGS=-pthread CXXFLAGS=-pthread ./configure --with-mit-threads=no

OpenBSD 2.8 Notes
.................

Our users have reported that OpenBSD 2.8 has a threading bug that causes
problems with MySQL.  The OpenBSD Developers have fixed the problem,
but as of January 25, 2001, it's only available in the "-current"
branch.  The symptoms of this threading bug are slow response, high
load, high CPU usage, and crashes.

If you get an error like `Error in accept:: Bad file descriptor' or
error 9 when trying to open tables or directories, the problem is
probably that you have not allocated enough file descriptors for MySQL.

In this case, try starting `mysqld_safe' as `root' with the following
options:

     mysqld_safe --user=mysql --open-files-limit=2048 &

BSD/OS Version 2.x Notes
........................

If you get the following error when compiling MySQL, your `ulimit'
value for virtual memory is too low:

     item_func.h: In method
     `Item_func_ge::Item_func_ge(const Item_func_ge &)':
     item_func.h:28: virtual memory exhausted
     make[2]: *** [item_func.o] Error 1

Try using `ulimit -v 80000' and run `make' again.  If this doesn't work
and you are using `bash', try switching to `csh' or `sh'; some BSDI
users have reported problems with `bash' and `ulimit'.

If you are using `gcc', you may also use have to use the
`--with-low-memory' flag for `configure' to be able to compile
`sql_yacc.cc'.

If you get problems with the current date in MySQL, setting the `TZ'
variable will probably help.  *Note Environment variables::.

BSD/OS Version 3.x Notes
........................

Upgrade to BSD/OS Version 3.1.  If that is not possible, install
BSDIpatch M300-038.

Use the following command when configuring MySQL:

     env CXX=shlicc++ CC=shlicc2 \
     ./configure \
         --prefix=/usr/local/mysql \
         --localstatedir=/var/mysql \
         --without-perl \
         --with-unix-socket-path=/var/mysql/mysql.sock

The following is also known to work:

     env CC=gcc CXX=gcc CXXFLAGS=-O3 \
     ./configure \
         --prefix=/usr/local/mysql \
         --with-unix-socket-path=/var/mysql/mysql.sock

You can change the directory locations if you wish, or just use the
defaults by not specifying any locations.

If you have problems with performance under heavy load, try using the
`--skip-thread-priority' option to `mysqld'!  This will run all threads
with the same priority. On BSDI Version 3.1, this gives better
performance, at least until BSDI fixes its thread scheduler.

If you get the error `virtual memory exhausted' while compiling, you
should try using `ulimit -v 80000' and running `make' again.  If this
doesn't work and you are using `bash', try switching to `csh' or `sh';
some BSDI users have reported problems with `bash' and `ulimit'.

BSD/OS Version 4.x Notes
........................

BSDI Version 4.x has some thread-related bugs.  If you want to use
MySQL on this, you should install all thread-related patches.  At least
M400-023 should be installed.

On some BSDI Version 4.x systems, you may get problems with shared
libraries.  The symptom is that you can't execute any client programs,
for example, `mysqladmin'.  In this case, you need to reconfigure not
to use shared libraries with the `--disable-shared' option to configure.

Some customers have had problems on BSDI 4.0.1 that the `mysqld' binary
after a while can't open tables.  This is because some
library/system-related bug causes `mysqld' to change current directory
without having asked for that to happen.

The fix is to either upgrade MySQL to at least version 3.23.34 or, after
running `configure', remove the line `#define HAVE_REALPATH' from
`config.h' before running `make'.

Note that this means that you can't symbolically link a database
directories to another database directory or symbolic link a table to
another database on BSDI.  (Making a symbolic link to another disk is
okay).

Other Unix Notes
----------------

HP-UX Version 10.20 Notes
.........................

There are a couple of small problems when compiling MySQL on HP-UX.  We
recommend that you use `gcc' instead of the HP-UX native compiler,
because `gcc' produces better code.

We recommend using `gcc' 2.95 on HP-UX.  Don't use high optimization
flags (such as `-O6') because they may not be safe on HP-UX.

The following `configure' line should work with `gcc' 2.95:

     CFLAGS="-I/opt/dce/include -fpic" \
     CXXFLAGS="-I/opt/dce/include -felide-constructors -fno-exceptions \
     -fno-rtti" \
     CXX=gcc \
     ./configure --with-pthread \
         --with-named-thread-libs='-ldce' \
         --prefix=/usr/local/mysql --disable-shared

The following `configure' line should work with `gcc' 3.1:

     CFLAGS="-DHPUX -I/opt/dce/include -O3 -fPIC" CXX=gcc \
     CXXFLAGS="-DHPUX -I/opt/dce/include -felide-constructors \
         -fno-exceptions -fno-rtti -O3 -fPIC" \
     ./configure --prefix=/usr/local/mysql \
         --with-extra-charsets=complex --enable-thread-safe-client \
         --enable-local-infile  --with-pthread \
         --with-named-thread-libs=-ldce --with-lib-ccflags=-fPIC
         --disable-shared

HP-UX Version 11.x Notes
........................

For HP-UX Version 11.x, we recommend MySQL 3.23.15 or later.

Because of some critical bugs in the standard HP-UX libraries, you
should install the following patches before trying to run MySQL on
HP-UX 11.0:

     PHKL_22840 Streams cumulative
     PHNE_22397 ARPA cumulative

This will solve the problem of getting `EWOULDBLOCK' from `recv()' and
`EBADF' from `accept()' in threaded applications.

If you are using `gcc' 2.95.1 on an unpatched HP-UX 11.x system, you
will get the error:

     In file included from /usr/include/unistd.h:11,
                      from ../include/global.h:125,
                      from mysql_priv.h:15,
                      from item.cc:19:
     /usr/include/sys/unistd.h:184: declaration of C function ...
     /usr/include/sys/pthread.h:440: previous declaration ...
     In file included from item.h:306,
                      from mysql_priv.h:158,
                      from item.cc:19:

The problem is that HP-UX doesn't define `pthreads_atfork()'
consistently.  It has conflicting prototypes in
`/usr/include/sys/unistd.h':184 and `/usr/include/sys/pthread.h':440.

One solution is to copy `/usr/include/sys/unistd.h' into
`mysql/include' and edit `unistd.h' and change it to match the
definition in `pthread.h'.  Look for this line:

     extern int pthread_atfork(void (*prepare)(), void (*parent)(),
                                               void (*child)());

Change it to look like this:

     extern int pthread_atfork(void (*prepare)(void), void (*parent)(void),
                                               void (*child)(void));

After making the change, the following `configure' line should work:

     CFLAGS="-fomit-frame-pointer -O3 -fpic" CXX=gcc \
     CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti -O3" \
     ./configure --prefix=/usr/local/mysql --disable-shared

If you are using MySQL 4.0.5 with the HP-UX compiler, you can use the
following command (which has been tested with `cc' B.11.11.04):

     CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure \
         --with-extra-character-set=complex

You can ignore any errors of the following type:

     aCC: warning 901: unknown option: `-3': use +help for online
     documentation

If you get the following error from `configure', verify that you don't
have the path to the K&R compiler before the path to the HP-UX C and
C++ compiler:

     checking for cc option to accept ANSI C... no
     configure: error: MySQL requires an ANSI C compiler (and a C++ compiler).
     Try gcc. See the Installation chapter in the Reference Manual.

Another reason for not being able to compile is that you didn't define
the `+DD64' flags as just described.

Another possibility for HP-UX 11 is to use MySQL binaries for HP-UX
10.20.  We have received reports from some users that these binaries
work fine on HP-UX 11.00. If you encounter problems, be sure to check
your HP-UX patch level.

IBM-AIX notes
.............

Automatic detection of `xlC' is missing from Autoconf, so a number of
variables need to be set before running `configure'. The following
example uses the IBM compiler:

     export CC="xlc_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192 "
     export CXX="xlC_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192"
     export CFLAGS="-I /usr/local/include"
     export LDFLAGS="-L /usr/local/lib"
     export CPPFLAGS=$CFLAGS
     export CXXFLAGS=$CFLAGS

     ./configure --prefix=/usr/local \
                     --localstatedir=/var/mysql \
                     --sbindir='/usr/local/bin' \
                     --libexecdir='/usr/local/bin' \
                     --enable-thread-safe-client \
                     --enable-large-files

The preceding options are used to compile the MySQL distribution that
can be found at `http://www-frec.bull.com/'.

If you change the `-O3' to `-O2' in the preceding `configure' line, you
must also remove the `-qstrict' option. This is a limitation in the IBM
C compiler.

If you are using `gcc' or `egcs' to compile MySQL, you _must_ use the
`-fno-exceptions' flag, because the exception handling in `gcc'/`egcs'
is not thread-safe!  (This is tested with `egcs' 1.1.)  There are also
some known problems with IBM's assembler that may cause it to generate
bad code when used with `gcc'.

We recommend the following `configure' line with `egcs' and `gcc' 2.95
on AIX:

     CC="gcc -pipe -mcpu=power -Wa,-many" \
     CXX="gcc -pipe -mcpu=power -Wa,-many" \
     CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti" \
     ./configure --prefix=/usr/local/mysql --with-low-memory

The `-Wa,-many' option is necessary for the compile to be successful.
IBM is aware of this problem but is in no hurry to fix it because of the
workaround that is available.  We don't know if the `-fno-exceptions'
is required with `gcc' 2.95, but because MySQL doesn't use exceptions
and the option generates faster code, we recommend that you should
always use it with `egcs' / `gcc'.

If you get a problem with assembler code, try changing the `-mcpu=XXX'
option to match your CPU. Typically `power2', `power', or `powerpc' may
need to be used.  Alternatively, you might need to use `604' or `604e'.
We are not positive but suspect that `power' would likely be safe most
of the time, even on a power2 machine.

If you don't know what your CPU is, execute a `uname -m' command.  It
will produce a string that looks like `000514676700', with a format of
`xxyyyyyymmss' where `xx' and `ss' are always `00', `yyyyyy' is a
unique system ID and `mm' is the ID of the CPU Planar.  A chart of
these values can be found at
`http://publib.boulder.ibm.com/doc_link/en_US/a_doc_lib/cmds/aixcmds5/uname.htm'.
This will give you a machine type and a machine model you can use to
determine what type of CPU you have.

If you have problems with signals (MySQL dies unexpectedly under high
load), you may have found an OS bug with threads and signals.  In this
case, you can tell MySQL not to use signals by configuring as follows:

     CFLAGS=-DDONT_USE_THR_ALARM CXX=gcc \
     CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti \
     -DDONT_USE_THR_ALARM" \
     ./configure --prefix=/usr/local/mysql --with-debug \
         --with-low-memory

This doesn't affect the performance of MySQL, but has the side effect
that you can't kill clients that are "sleeping" on a connection with
`mysqladmin kill' or `mysqladmin shutdown'.  Instead, the client will
die when it issues its next command.

On some versions of AIX, linking with `libbind.a' makes
`getservbyname()' dump core.  This is an AIX bug and should be reported
to IBM.

For AIX 4.2.1 and `gcc', you have to make the following changes.

After configuring, edit `config.h' and `include/my_config.h' and change
the line that says this:

     #define HAVE_SNPRINTF 1

to this:

     #undef HAVE_SNPRINTF

And finally, in `mysqld.cc', you need to add a prototype for
`initgroups()'.

     #ifdef _AIX41
     extern "C" int initgroups(const char *,int);
     #endif

If you need to allocate a lot of memory to the `mysqld' process, it's
not enough to just use `ulimit -d unlimited'. You may also have to
modify `mysqld_safe' to add a line something like this:

     export LDR_CNTRL='MAXDATA=0x80000000'

You can find more information about using a lot of memory at
`http://publib16.boulder.ibm.com/pseries/en_US/aixprggd/genprogc/lrg_prg_support.htm'.

SunOS 4 Notes
.............

On SunOS 4, MIT-pthreads is needed to compile MySQL. This in turn means
you will need GNU `make'.

Some SunOS 4 systems have problems with dynamic libraries and `libtool'.
You can use the following `configure' line to avoid this problem:

     ./configure --disable-shared --with-mysqld-ldflags=-all-static

When compiling `readline', you may get warnings about duplicate defines.
These can be ignored.

When compiling `mysqld', there will be some `implicit declaration of
function' warnings. These can be ignored.

Alpha-DEC-UNIX Notes (Tru64)
............................

If you are using `egcs' 1.1.2 on Digital Unix, you should upgrade to
`gcc' 2.95.2, because `egcs' on DEC has some serious bugs!

When compiling threaded programs under Digital Unix, the documentation
recommends using the `-pthread' option for `cc' and `cxx' and the
`-lmach -lexc' libraries (in addition to `-lpthread').  You should run
`configure' something like this:

     CC="cc -pthread" CXX="cxx -pthread -O" \
     ./configure --with-named-thread-libs="-lpthread -lmach -lexc -lc"

When compiling `mysqld', you may see a couple of warnings like this:

     mysqld.cc: In function void handle_connections()':
     mysqld.cc:626: passing long unsigned int *' as argument 3 of
     accept(int,sockadddr *, int *)'

You can safely ignore these warnings.  They occur because `configure'
can detect only errors, not warnings.

If you start the server directly from the command line, you may have
problems with it dying when you log out.  (When you log out, your
outstanding processes receive a `SIGHUP' signal.)  If so, try starting
the server like this:

     nohup mysqld [OPTIONS] &

`nohup' causes the command following it to ignore any `SIGHUP' signal
sent from the terminal.  Alternatively, start the server by running
`mysqld_safe', which invokes `mysqld' using `nohup' for you.  *Note
`mysqld_safe': mysqld_safe.

If you get a problem when compiling `mysys/get_opt.c', just remove the
`#define _NO_PROTO' line from the start of that file.

If you are using Compaq's CC compiler, the following `configure' line
should work:

     CC="cc -pthread"
     CFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all -arch host"
     CXX="cxx -pthread"
     CXXFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all \
         -arch host -noexceptions -nortti"
     export CC CFLAGS CXX CXXFLAGS
     ./configure \
         --prefix=/usr/local/mysql \
         --with-low-memory \
         --enable-large-files \
         --enable-shared=yes \
         --with-named-thread-libs="-lpthread -lmach -lexc -lc"
     gnumake

If you get a problem with `libtool' when compiling with shared libraries
as just shown, when linking `mysql', you should be able to get around
this by issuing these commands:

     cd mysql
     /bin/sh ../libtool --mode=link cxx -pthread  -O3 -DDBUG_OFF \
         -O4 -ansi_alias -ansi_args -fast -inline speed \
         -speculate all \ -arch host  -DUNDEF_HAVE_GETHOSTBYNAME_R \
         -o mysql  mysql.o readline.o sql_string.o completion_hash.o \
         ../readline/libreadline.a -lcurses \
         ../libmysql/.libs/libmysqlclient.so  -lm
     cd ..
     gnumake
     gnumake install
     scripts/mysql_install_db

Alpha-DEC-OSF/1 Notes
.....................

If you have problems compiling and have DEC `CC' and `gcc' installed,
try running `configure' like this:

     CC=cc CFLAGS=-O CXX=gcc CXXFLAGS=-O3 \
     ./configure --prefix=/usr/local/mysql

If you get problems with the `c_asm.h' file, you can create and use a
'dummy' `c_asm.h' file with:

     touch include/c_asm.h
     CC=gcc CFLAGS=-I./include \
     CXX=gcc CXXFLAGS=-O3 \
     ./configure --prefix=/usr/local/mysql

Note that the following problems with the `ld' program can be fixed by
downloading the latest DEC (Compaq) patch kit from:
`http://ftp.support.compaq.com/public/unix/'.

On OSF/1 V4.0D and compiler "DEC C V5.6-071 on Digital Unix V4.0 (Rev.
878)," the compiler had some strange behavior (undefined `asm' symbols).
`/bin/ld' also appears to be broken (problems with `_exit undefined'
errors occurring while linking `mysqld').  On this system, we have
managed to compile MySQL with the following `configure' line, after
replacing `/bin/ld' with the version from OSF 4.0C:

     CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql

With the Digital compiler "C++ V6.1-029," the following should work:

     CC=cc -pthread
     CFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed \
            -speculate all -arch host
     CXX=cxx -pthread
     CXXFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed \
              -speculate all -arch host -noexceptions -nortti
     export CC CFLAGS CXX CXXFLAGS
     ./configure --prefix=/usr/mysql/mysql \
                 --with-mysqld-ldflags=-all-static --disable-shared \
                 --with-named-thread-libs="-lmach -lexc -lc"

In some versions of OSF/1, the `alloca()' function is broken. Fix this
by removing the line in `config.h' that defines `'HAVE_ALLOCA''.

The `alloca()' function also may have an incorrect prototype in
`/usr/include/alloca.h'.  This warning resulting from this can be
ignored.

`configure' will use the following thread libraries automatically:
`--with-named-thread-libs="-lpthread -lmach -lexc -lc"'.

When using `gcc', you can also try running `configure' like this:

     CFLAGS=-D_PTHREAD_USE_D4 CXX=gcc CXXFLAGS=-O3 ./configure ...

If you have problems with signals (MySQL dies unexpectedly under high
load), you may have found an OS bug with threads and signals. In this
case, you can tell MySQL not to use signals by configuring with:

     CFLAGS=-DDONT_USE_THR_ALARM \
     CXXFLAGS=-DDONT_USE_THR_ALARM \
     ./configure ...

This doesn't affect the performance of MySQL, but has the side effect
that you can't kill clients that are "sleeping" on a connection with
`mysqladmin kill' or `mysqladmin shutdown'.  Instead, the client will
die when it issues its next command.

With `gcc' 2.95.2, you will probably run into the following compile
error:

     sql_acl.cc:1456: Internal compiler error in `scan_region',
     at except.c:2566
     Please submit a full bug report.

To fix this, you should change to the `sql' directory and do a
cut-and-paste of the last `gcc' line, but change `-O3' to `-O0' (or add
`-O0' immediately after `gcc' if you don't have any `-O' option on your
compile line).  After this is done, you can just change back to the
top-level directory and run `make' again.

SGI Irix Notes
..............

If you are using Irix Version 6.5.3 or newer, `mysqld' will be able to
create threads only if you run it as a user that has `CAP_SCHED_MGT'
privileges (such as `root') or give the `mysqld' server this privilege
with the following shell command:

     chcap "CAP_SCHED_MGT+epi" /opt/mysql/libexec/mysqld

You may have to undefine some symbols in `config.h' after running
`configure' and before compiling.

In some Irix implementations, the `alloca()' function is broken.  If the
`mysqld' server dies on some `SELECT' statements, remove the lines from
`config.h' that define `HAVE_ALLOC' and `HAVE_ALLOCA_H'.  If
`mysqladmin create' doesn't work, remove the line from `config.h' that
defines `HAVE_READDIR_R'.  You may have to remove the `HAVE_TERM_H'
line as well.

SGI recommends that you install all the patches on this page as a set:
`http://support.sgi.com/surfzone/patches/patchset/6.2_indigo.rps.html'

At the very minimum, you should install the latest kernel rollup, the
latest `rld' rollup, and the latest `libc' rollup.

You definitely need all the POSIX patches on this page, for pthreads
support:

`http://support.sgi.com/surfzone/patches/patchset/6.2_posix.rps.html'

If you get the something like the following error when compiling
`mysql.cc':

     "/usr/include/curses.h", line 82: error(1084):
     invalid combination of type

Type the following in the top-level directory of your MySQL source tree:

     extra/replace bool curses_bool < /usr/include/curses.h > include/curses.h
     make

There have also been reports of scheduling problems.  If only one
thread is running, performance is slow.  Avoid this by starting another
client.  This may lead to a two-to-tenfold increase in execution speed
thereafter for the other thread.  This is a poorly understood problem
with Irix threads; you may have to improvise to find solutions until
this can be fixed.

If you are compiling with `gcc', you can use the following `configure'
command:

     CC=gcc CXX=gcc CXXFLAGS=-O3 \
     ./configure --prefix=/usr/local/mysql --enable-thread-safe-client \
         --with-named-thread-libs=-lpthread

On Irix 6.5.11 with native Irix C and C++ compilers ver. 7.3.1.2, the
following is reported to work

     CC=cc CXX=CC CFLAGS='-O3 -n32 -TARG:platform=IP22 -I/usr/local/include \
     -L/usr/local/lib' CXXFLAGS='-O3 -n32 -TARG:platform=IP22 \
     -I/usr/local/include -L/usr/local/lib' \
     ./configure --prefix=/usr/local/mysql --with-innodb --with-berkeley-db \
         --with-libwrap=/usr/local \
         --with-named-curses-libs=/usr/local/lib/libncurses.a

SCO Notes
.........

The current port is tested only on "sco3.2v5.0.5," "sco3.2v5.0.6," and
"sco3.2v5.0.7" systems. There has also been a lot of progress on a port
to "sco 3.2v4.2."  Open Server 5.0.8(Legend) will have native threads
and allow files greater than 2GB.  The current maximum file size is 2GB.

We have been able to compile MySQL with the following `configure'
command on on OpenServer with `gcc' 2.95.3.

     CC=gcc CXX=gcc ./configure --prefix=/usr/local/mysql \
         --enable-thread-safe-client --with-innodb \
         --with-openssl --with-vio --with-extra-charsets=complex

`gcc' is available at
`ftp://ftp.sco.com/pub/openserver5/opensrc/gnutools-5.0.7Kj'.

This development system requires the OpenServer Execution Enviroment
Supplement oss646B on OpenServer 5.0.6 and oss656B and The OpenSource
libraries found in gwxlibs.  All OpenSource tools are in the `opensrc'
directory.  They are available at
`ftp://ftp.sco.com/pub/openserver5/opensrc/'.

We recommend using the latest production release of MySQL.  Currently
MySQL-4.0.x is the latest production release.  There were some problems
with MySQL 4.0.17 and MySQL 4.0.18, but they have now been fixed.

SCO provides operating system patches at
`ftp://ftp.sco.com/pub/openserver5' for OpenServer 5.0.[0-6] and
`ftp://ftp.sco.com/pub/openserverv5/507' for OpenServer 5.0.7.

SCO provides information about security fixes at
`ftp://ftp.sco.com/pub/security/OpenServer' for OpenServer 5.0.x.

The maximum file size on an OpenSever 5.0.x system is 2GB.

The total memory which could be allocated for streams buffers, clists
and lock records cannot exceed 60MB on OpenServer 5.0.x.

Streams buffers are allocated in units of 4096 byte pages, clists are 70
bytes each, and lock records are 64 bytes each, so:

     (NSTRPAGES * 4096) + (NCLIST * 70) + (MAX_FLCKREC * 64) <= 62914560

Follow this procedure to configure the Database Services option. If you
are unsure whether an application requires this, see the documentation
provided with the application.

  1. Log in as `root'.

  2. Enable the SUDS driver by editing the `/etc/conf/sdevice.d/suds'
     file.  Change the `N' in the second field to a `Y'.

  3. Use `mkdev aio' or the Hardware/Kernel Manager to enable support
     for asynchronous I/O and relink the kernel. To allow users to lock
     down memory for use with this type of I/O, update the
     aiomemlock(F) file. This file should be updated to include the
     names of users that can use AIO and the maximum amounts of memory
     they can lock down.

  4. Many applications use setuid binaries so that you need to specify
     only a single user. See the documentation provided with the
     application to see if this is the case for your application.

After you complete this process, reboot the system to create a new
kernel incorporating these changes.

By default, the entries in `/etc/conf/cf.d/mtune' are set as follows:

     Value           Default         Min             Max
     -----           -------         ---             ---
     NBUF            0               24              450000
     NHBUF           0               32              524288
     NMPBUF          0               12              512
     MAX_INODE       0               100             64000
     MAX_FILE        0               100             64000
     CTBUFSIZE       128             0               256
     MAX_PROC        0               50              16000
     MAX_REGION      0               500             160000
     NCLIST          170             120             16640
     MAXUP           100             15              16000
     NOFILES         110             60              11000
     NHINODE         128             64              8192
     NAUTOUP         10              0               60
     NGROUPS         8               0               128
     BDFLUSHR        30              1               300
     MAX_FLCKREC     0               50              16000
     PUTBUFSZ        8000            2000            20000
     MAXSLICE        100             25              100
     ULIMIT          4194303         2048            4194303
     * Streams Parameters
     NSTREAM         64              1               32768
     NSTRPUSH        9               9               9
     NMUXLINK        192             1               4096
     STRMSGSZ        16384           4096            524288
     STRCTLSZ        1024            1024            1024
     STRMAXBLK       524288          4096            524288
     NSTRPAGES       500             0               8000
     STRSPLITFRAC    80              50              100
     NLOG            3               3               3
     NUMSP           64              1               256
     NUMTIM          16              1               8192
     NUMTRW          16              1               8192
     * Semaphore Parameters
     SEMMAP          10              10              8192
     SEMMNI          10              10              8192
     SEMMNS          60              60              8192
     SEMMNU          30              10              8192
     SEMMSL          25              25              150
     SEMOPM          10              10              1024
     SEMUME          10              10              25
     SEMVMX          32767           32767           32767
     SEMAEM          16384           16384           16384
     * Shared Memory Parameters
     SHMMAX          524288          131072          2147483647
     SHMMIN          1               1               1
     SHMMNI          100             100             2000
     FILE            0               100             64000
     NMOUNT          0               4               256
     NPROC           0               50              16000
     NREGION         0               500             160000

We recommend setting these values as follows:

`NOFILES' should be 4096 or 2048.

`MAXUP' should be 2048.

To make changes to the kernel, `cd' to `/etc/conf/bin' and use
`./idtune' NAME PARAMETER to make the changes. For example, to change
`SEMMS' to `200', execute these commands as `root':

     # cd /etc/conf/bin
     # ./idtune SEMMNS 200

We recommend tuning the system, but the proper parameter values to use
depend on the number of users accessing the application or database and
size the of the database (that is, the used buffer pool). The following
will affect the following kernel parameters defined in
`/etc/conf/cf.d/stune':

`SHMMAX' (recommended setting: 128MB) and `SHMSEG' (recommended
setting: 15).  These parameters have influence on the MySQL database
engine to create user buffer pools.

`NOFILES' and `MAXUP' should be at to at least 2048.

`MAXPROC' should be set to at least 3000/4000 (depends on number of
users) or more.

Also is recommended to use following formula to count value for
`SEMMSL', `SEMMNS' and `SEMMNU':

     SEMMSL = 13

The 13 is what has been found to be the best for both Progress and
MySQL.

`SEMMNS' = `SEMMSL' * number of db servers to be run on the system.

Set `SEMMNS' to the value of `SEMMSL' multiplied by the number of db
servers (maximum) that you will be running on the system at one time.

     SEMMNU = SEMMNS

Set the value of `SEMMNU' to equal the value of `SEMMNS'. You could
probably set this to 75% of `SEMMNS', but this is a conservative
estimate.

You need to at least install the "SCO OpenServer Linker and Application
Development Libraries" or the OpenServer Development System to use
`gcc'.  You cannot just use the GCC Dev system without installing one
of these.

You should get the FSU Pthreads package and install it first. This can
be found at
`http://moss.csc.ncsu.edu/~mueller/ftp/pub/PART/pthreads.tar.gz'.  You
can also get a precompiled package from
`ftp://ftp.zenez.com/pub/zenez/prgms/FSU-threads-3.14.tar.gz'.

FSU Pthreads can be compiled with SCO Unix 4.2 with tcpip, or using
OpenServer 3.0 or Open Desktop 3.0 (OS 3.0 ODT 3.0) with the SCO
Development System installed using a good port of GCC 2.5.x. For ODT or
OS 3.0, you will need a good port of GCC 2.5.x. There are a lot of
problems without a good port. The port for this product requires the
SCO Unix Development system. Without it, you are missing the libraries
and the linker that is needed.  You will also need
`SCO-3.2v4.2-includes.tar.gz'. This file contains the changes to the
SCO Development include files that are needed to get MySQL to build.
You need to replace the existing system include files with these
modified header files.  They can be obtained from
`ftp://ftp.zenez.com/pub/zenez/prgms/SCO-3.2v4.2-includes.tar.gz'.

To build FSU Pthreads on your system, all you should need to do is run
GNU `make'.  The `Makefile' in FSU-threads-3.14.tar.gz is already set
up to make FSU-threads.

You can run `./configure' in the `threads/src' directory and select the
SCO OpenServer option. This command copies `Makefile.SCO5' to
`Makefile'.  Then run `make'.

To install in the default `/usr/include' directory, log in as `root',
then `cd' to the `thread/src' directory and run `make install'.

Remember that you must use GNU `make' when making MySQL.

*Note*: If you don't start `mysqld_safe' as `root', you probably will
get only the default 110 open files per process. `mysqld' will write a
note about this in the log file.

With SCO 3.2V4.2, you should use FSU Pthreads version 3.14 or newer.
The following `configure' command should work:

     CFLAGS="-D_XOPEN_XPG4" CXX=gcc CXXFLAGS="-D_XOPEN_XPG4" \
     ./configure \
         --prefix=/usr/local/mysql \
         --with-named-thread-libs="-lgthreads -lsocket -lgen -lgthreads" \
         --with-named-curses-libs="-lcurses"

You may get some problems with some include files. In this case, you can
find new SCO-specific include files at
`ftp://ftp.zenez.com/pub/zenez/prgms/SCO-3.2v4.2-includes.tar.gz'.

You should unpack this file in the `include' directory of your MySQL
source tree.

SCO development notes:

   bullet MySQL should automatically detect FSU Pthreads and link
     `mysqld' with `-lgthreads -lsocket -lgthreads'.

   bullet The SCO development libraries are re-entrant in FSU Pthreads.
     SCO claims that its library functions are re-entrant, so they must
     be re-entrant with FSU Pthreads. FSU Pthreads on OpenServer tries
     to use the SCO scheme to make re-entrant libraries.

   bullet FSU Pthreads (at least the version at `ftp::/ftp.zenez.com')
     comes linked with GNU `malloc'. If you encounter problems with
     memory usage, make sure that `gmalloc.o' is included in
     `libgthreads.a' and `libgthreads.so'.

   bullet In FSU Pthreads, the following system calls are
     pthreads-aware: `read()', `write()', `getmsg()', `connect()',
     `accept(),' `select()', and `wait()'.

   bullet The CSSA-2001-SCO.35.2 (the patch is listed in custom as
     erg711905-dscr_remap security patch (version 2.0.0)) breaks FSU
     threads and makes `mysqld' unstable. You have to remove this one
     if you want to run `mysqld' on an OpenServer 5.0.6 machine.

   bullet SCO provides operating system patches at
     `ftp://ftp.sco.com/pub/openserver5' for OpenServer 5.0.x.

   bullet SCO provides security fixes and `libsocket.so.2' at
     `ftp://ftp.sco.com/pub/security/OpenServer' and
     `ftp://ftp.sco.com/pub/security/sse' for OpenServer 5.0.x.

   bullet Pre-OSR506 security fixes. Also, the `telnetd' fix at
     `ftp://stage.caldera.com/pub/security/openserver/' or
     `ftp://stage.caldera.com/pub/security/openserver/CSSA-2001-SCO.10/'
     as both `libsocket.so.2' and `libresolv.so.1' with instructions for
     installing on pre-OSR506 systems.

     It's probably a good idea to install these patches before trying
     to compile/use MySQL.


Begining with Legend, OpenServer will have native threads and no 2GB
file size limit.

SCO UnixWare Version 7.1.x Notes
................................

We recommend using the latest production release of MySQL.  Currently
this is MySQL 4.0.x.  Should you choose to use an older release of
MySQL on UnixWare 7.1.x, you must use a version of MySQL at least as
recent as 3.22.13 to get fixes for some portability and OS problems.

We have been able to compile MySQL with the following `configure'
command on UnixWare Version 7.1.x:

     CC="cc" CFLAGS="-I/usr/local/include" \
     CXX="CC" CXXFLAGS="-I/usr/local/include" \
     ./configure --prefix=/usr/local/mysql \
         --enable-thread-safe-client --with-berkeley-db=./bdb \
         --with-innodb --with-openssl --with-extra-charsets=complex

If you want to use `gcc', you must use `gcc' 2.95.3 or newer.

     CC=gcc CXX=g++ ./configure --prefix=/usr/local/mysql

SCO provides operating system patches at
`ftp://ftp.sco.com/pub/unixware7' for UnixWare 7.1.1,
`ftp://ftp.sco.com/pub/unixware7/713/' for UnixWare 7.1.3,
`ftp://ftp.sco.com/pub/unixware7/714/' for UnixWare 7.1.4, and
`ftp://ftp.sco.com/pub/openunix8' for OpenUNIX 8.0.0.

SCO provides information about security fixes at
`ftp://ftp.sco.com/pub/security/OpenUNIX' for OpenUNIX and
`ftp://ftp.sco.com/pub/security/UnixWare' for UnixWare.

By default, the maximum file size on a UnixWare 7 system is 1GB.  Many
OS utilities have a limitation of 2GB.  The maximum possible file size
on UnixWare 7 is 1TB with VXFS.

To enable large file support on UnixWare 7.1.x, run `fsadm'.

     # fsadm -Fvxfs -o largefiles /
     # fsadm /                    * Note
     # ulimit unlimited
     # cd /etc/conf/bin
     # ./idtune SFSZLIM 0x7FFFFFFF            ** Note
     # ./idtune HFSZLIM 0x7FFFFFFF            ** Note
     # ./idbuild -B

     * This should report "largefiles".
     ** 0x7FFFFFFF represents infinity for these values.

Reboot the system using `shutdown'.

By default, the entries in `/etc/conf/cf.d/mtune' are set to:

     Value           Default         Min             Max
     -----           -------         ---             ---
     SVMMLIM         0x9000000       0x1000000       0x7FFFFFFF
     HVMMLIM         0x9000000       0x1000000       0x7FFFFFFF
     SSTKLIM         0x1000000       0x2000          0x7FFFFFFF
     HSTKLIM         0x1000000       0x2000          0x7FFFFFFF

We recommend setting these values as follows:

     SDATLIM 0x7FFFFFFF
     HDATLIM 0x7FFFFFFF
     SSTKLIM 0x7FFFFFFF
     HSTKLIM 0x7FFFFFFF
     SVMMLIM 0x7FFFFFFF
     HVMMLIM 0x7FFFFFFF
     SFNOLIM 2048
     HFNOLIM 2048

We recommend tuning the system, but the proper parameter values to use
depend on the number of users accessing the application or database and
size the of the database (that is, the used buffer pool). The following
will affect the following kernel parameters defined in
`/etc/conf/cf.d/stune':

`SHMMAX' (recommended setting: 128MB) and `SHMSEG' (recommended
setting: 15).  These parameters have influence on the MySQL database
engine to create user buffer pools.

`SFNOLIM' and `HFNOLIM' should be at maximum 2048.

`NPROC' should be set to at least 3000/4000 (depends on number of
users).

Also is recommended to use following formula to count value for
`SEMMSL', `SEMMNS', and `SEMMNU':

     SEMMSL = 13

13 is what has been found to be the best for both Progress and MySQL.

`SEMMNS' = `SEMMSL' * number of db servers to be run on the system.

Set `SEMMNS' to the value of `SEMMSL' multiplied by the number of db
servers (maximum) that you will be running on the system at one time.

`SEMMNU' = `SEMMNS'

Set the value of `SEMMNU' to equal the value of `SEMMNS'. You could
probably set this to 75% of `SEMMNS', but this is a conservative
estimate.

OS/2 Notes
----------

MySQL uses quite a few open files. Because of this, you should add
something like the following to your `CONFIG.SYS' file:

     SET EMXOPT=-c -n -h1024

If you don't do this, you will probably run into the following error:

     File 'XXXX' not found (Errcode: 24)

When using MySQL with OS/2 Warp 3, FixPack 29 or above is required.
With OS/2 Warp 4, FixPack 4 or above is required. This is a requirement
of the Pthreads library.  MySQL must be installed on a partition with a
type that supports long filenames, such as HPFS, FAT32, and so on.

The `INSTALL.CMD' script must be run from OS/2's own `CMD.EXE' and may
not work with replacement shells such as `4OS2.EXE'.

The `scripts/mysql-install-db' script has been renamed.  It is now
called `install.cmd' and is a REXX script, which will set up the default
MySQL security settings and create the WorkPlace Shell icons for MySQL.

Dynamic module support is compiled in but not fully tested. Dynamic
modules should be compiled using the Pthreads runtime library.

     gcc -Zdll -Zmt -Zcrtdll=pthrdrtl -I../include -I../regex -I.. \
         -o example udf_example.cc -L../lib -lmysqlclient udf_example.def
     mv example.dll example.udf

*Note*: Due to limitations in OS/2, UDF module name stems must not
exceed eight characters. Modules are stored in the `/mysql2/udf'
directory; the `safe-mysqld.cmd' script will put this directory in the
`BEGINLIBPATH' environment variable. When using UDF modules, specified
extensions are ignored--it is assumed to be `.udf'.  For example, in
Unix, the shared module might be named `example.so' and you would load
a function from it like this:

     mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME 'example.so';

In OS/2, the module would be named `example.udf', but you would not
specify the module extension:

     mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME 'example';

BeOS Notes
----------

We have in the past talked with some BeOS developers who have said that
MySQL is 80% ported to BeOS, but we haven't heard from them in a while.

Perl Installation Notes
=======================

Perl support for MySQL is provided by means of the `DBI'/`DBD' client
interface. The interface requires Perl Version 5.6.0 or later.  It
_will not work_ if you have an older version of Perl.

If you want to use transactions with Perl DBI, you need to have
`DBD::mysql' version 1.2216 or newer. Version 2.9003 or newer is
recommended.

If you are using the MySQL 4.1 client library, you must use
`DBD::mysql' 2.9003 or newer.

As of MySQL 3.22.8, Perl support is no longer included with MySQL
distributions. You can obtain the necessary modules from
`http://search.cpan.org' for Unix, or by using the ActiveState `ppm'
program on Windows. The following sections describe how to do this.

Perl support for MySQL must be installed if you want to run the MySQL
benchmark scripts.  *Note MySQL Benchmarks::.

Installing Perl on Unix
-----------------------

MySQL Perl support requires that you've installed MySQL client
programming support (libraries and header files).  Most installation
methods install the necessary files. However, if you installed MySQL
from RPM files on Linux, be sure that you've installed the developer
RPM.  The client programs are in the client RPM, but client programming
support is in the developer RPM.

If you want to install Perl support, the files you will need can be
obtained from the CPAN (Comprehensive Perl Archive Network) at
`http://search.cpan.org'.

The easiest way to install Perl modules on Unix is to use the `CPAN'
module. For example:

     shell> perl -MCPAN -e shell
     cpan> install DBI
     cpan> install DBD::mysql

The `DBD::mysql' installation runs a number of tests.  These tests
require being able to connect to the local MySQL server as the
anonymous user with no password. If you have removed anonymous accounts
or assigned them passwords, the tests fail. You can use `force install
DBD::mysql' to ignore the failed tests.

`DBI' requires the `Data::Dumper' module. It may already be installed;
if not, you should install it before installing `DBI'.

It is also possible to download the module distributions in the form of
compressed `tar' archives and build the modules manually. For example,
to unpack and build a DBI distribution, use a procedure such as this:

  1. Unpack the distribution into the current directory:
          shell> gunzip < DBI-VERSION.tar.gz | tar xvf -
     This command creates a directory named `DBI-VERSION'.

  2. Change location into the top-level directory of the unpacked
     distribution:
          shell> cd DBI-VERSION

  3. Build the distribution and compile everything:
          shell> perl Makefile.PL
          shell> make
          shell> make test
          shell> make install

The `make test' command is important because it verifies that the
module is working.  Note that when you run that command during the
`DBD::mysql' installation to exercise the interface code, the MySQL
server must be running or the test will fail.

It is a good idea to rebuild and reinstall the `DBD::mysql'
distribution whenever you install a new release of MySQL, particularly
if you notice symptoms such as that all your `DBI' scripts fail after
you upgrade MySQL.

If you don't have access rights to install Perl modules in the system
directory or if you want to install local Perl modules, the following
reference may be useful:
`http://servers.digitaldaze.com/extensions/perl/modules.html#modules'

Look under the heading "Installing New Modules that Require Locally
Installed Modules."

Installing ActiveState Perl on Windows
--------------------------------------

On Windows, you should do the following to install the MySQL `DBD'
module with ActiveState Perl:

   * Get ActiveState Perl from
     `http://www.activestate.com/Products/ActivePerl/' and install it.

   * Open a console window (a "DOS window").

   * If required, set the `HTTP_proxy' variable. For example, you might
     try:

          set HTTP_proxy=my.proxy.com:3128

   * Start the PPM program:

          C:\> C:\perl\bin\ppm.pl

   * If you have not already done so, install `DBI':

          ppm> install DBI

   * If this succeeds, run the following command:

          install \
          ftp://ftp.de.uu.net/pub/CPAN/authors/id/JWIED/DBD-mysql-1.2212.x86.ppd

This procedure should work at least with ActiveState Perl Version 5.6.

If you can't get the procedure to work, you should instead install the
MyODBC driver and connect to the MySQL server through ODBC:

     use DBI;
     $dbh= DBI->connect("DBI:ODBC:$dsn",$user,$password) ||
       die "Got error $DBI::errstr when connecting to $dsn\n";

Problems Using the Perl `DBI'/`DBD' Interface
---------------------------------------------

If Perl reports that it can't find the `../mysql/mysql.so' module, then
the problem is probably that Perl can't locate the shared library
`libmysqlclient.so'.

You should be able to fix this by one of the following methods:

   * Compile the `DBD::mysql' distribution with `perl Makefile.PL
     -static -config' rather than `perl Makefile.PL'.

   * Copy `libmysqlclient.so' to the directory where your other shared
     libraries are located (probably `/usr/lib' or `/lib').

   * Modify the `-L' options used to compile `DBD::mysql' to reflect
     the actual location of `libmysqlclient.so'.

   * On Linux, you can add the pathname of the directory where
     `libmysqlclient.so' is located to the `/etc/ld.so.conf' file.

   * Add the pathname of the directory where `libmysqlclient.so' is
     located to the `LD_RUN_PATH' environment variable. Some systems use
     `LD_LIBRARY_PATH' instead.

Note that you may also need to modify the `-L' options if there are
other libraries that the linker fails to find. For example, if the
linker cannot find `libc' because it is in `/lib' and the link command
specifies `-L/usr/lib', change the `-L' option to `-L/lib' or add
`-L/lib' to the existing link command.

If you get the following errors from `DBD::mysql', you are probably
using `gcc' (or using an old binary compiled with `gcc'):

     /usr/bin/perl: can't resolve symbol '__moddi3'
     /usr/bin/perl: can't resolve symbol '__divdi3'

Add `-L/usr/lib/gcc-lib/... -lgcc' to the link command when the
`mysql.so' library gets built (check the output from `make' for
`mysql.so' when you compile the Perl client).  The `-L' option should
specify the pathname of the directory where `libgcc.a' is located on
your system.

Another cause of this problem may be that Perl and MySQL aren't both
compiled with `gcc'.  In this case, you can solve the mismatch by
compiling both with `gcc'.

You may see the following error from `DBD::mysql' when you run the
tests:

     t/00base............install_driver(mysql) failed:
     Can't load '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql:
     ../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol:
     uncompress at /usr/lib/perl5/5.00503/i586-linux/DynaLoader.pm line 169.

This means that you need to include the `-lz' compression library on the
link line. That can be done by changing the following line in the file
`lib/DBD/mysql/Install.pm':

     $sysliblist .= " -lm";

Change that line to:

     $sysliblist .= " -lm -lz";

After this, you _must_ run `make realclean' and then proceed with the
installation from the beginning.

If you want to install DBI on SCO, you have to edit the `Makefile' in
DBI-XXX and each subdirectory.  Note that the following assumes `gcc'
2.95.2 or newer:

     OLD:                                  NEW:
     CC = cc                               CC = gcc
     CCCDLFLAGS = -KPIC -W1,-Bexport       CCCDLFLAGS = -fpic
     CCDLFLAGS = -wl,-Bexport              CCDLFLAGS =

     LD = ld                               LD = gcc -G -fpic
     LDDLFLAGS = -G -L/usr/local/lib       LDDLFLAGS = -L/usr/local/lib
     LDFLAGS = -belf -L/usr/local/lib      LDFLAGS = -L/usr/local/lib

     LD = ld                               LD = gcc -G -fpic
     OPTIMISE = -Od                        OPTIMISE = -O1

     OLD:
     CCCFLAGS = -belf -dy -w0 -U M_XENIX -DPERL_SCO5 -I/usr/local/include

     NEW:
     CCFLAGS = -U M_XENIX -DPERL_SCO5 -I/usr/local/include

These changes are necessary because the Perl dynaloader will not load
the `DBI' modules if they were compiled with `icc' or `cc'.

If you want to use the Perl module on a system that doesn't support
dynamic linking (such as SCO), you can generate a static version of
Perl that includes `DBI' and `DBD::mysql'.  The way this works is that
you generate a version of Perl with the `DBI' code linked in and
install it on top of your current Perl.  Then you use that to build a
version of Perl that additionally has the `DBD' code linked in, and
install that.

On SCO, you must have the following environment variables set:

     LD_LIBRARY_PATH=/lib:/usr/lib:/usr/local/lib:/usr/progressive/lib

Or:

     LD_LIBRARY_PATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\
         /usr/progressive/lib:/usr/skunk/lib
     LIBPATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\
         /usr/progressive/lib:/usr/skunk/lib
     MANPATH=scohelp:/usr/man:/usr/local1/man:/usr/local/man:\
         /usr/skunk/man:

First, create a Perl that includes a statically linked `DBI' module by
running these commands in the directory where your `DBI' distribution is
located:

     shell> perl Makefile.PL -static -config
     shell> make
     shell> make install
     shell> make perl

Then you must install the new Perl. The output of `make perl' will
indicate the exact `make' command you will need to execute to perform
the installation.  On SCO, this is `make -f Makefile.aperl inst_perl
MAP_TARGET=perl'.

Next, use the just-created Perl to create another Perl that also
includes a statically linked `DBD::mysql' by running these commands in
the directory where your `DBD::mysql' distribution is located:

     shell> perl Makefile.PL -static -config
     shell> make
     shell> make install
     shell> make perl

Finally, you should install this new Perl.  Again, the output of `make
perl' indicates the command to use.

MySQL Tutorial
**************

This chapter provides a tutorial introduction to MySQL by showing how
to use the `mysql' client program to create and use a simple database.
`mysql' (sometimes referred to as the "terminal monitor" or just
"monitor") is an interactive program that allows you to connect to a
MySQL server, run queries, and view the results.  `mysql' may also be
used in batch mode: you place your queries in a file beforehand, then
tell `mysql' to execute the contents of the file.  Both ways of using
`mysql' are covered here.

To see a list of options provided by `mysql', invoke it with the
`--help' option:

     shell> mysql --help

This chapter assumes that `mysql' is installed on your machine and that
a MySQL server is available to which you can connect.  If this is not
true, contact your MySQL administrator.  (If *you* are the
administrator, you will need to consult other sections of this manual.)

This chapter describes the entire process of setting up and using a
database.  If you are interested only in accessing an already-existing
database, you may want to skip over the sections that describe how to
create the database and the tables it contains.

Because this chapter is tutorial in nature, many details are necessarily
omitted.  Consult the relevant sections of the manual for more
information on the topics covered here.

Connecting to and Disconnecting from the Server
===============================================

To connect to the server, you'll usually need to provide a MySQL
username when you invoke `mysql' and, most likely, a password.  If the
server runs on a machine other than the one where you log in, you'll
also need to specify a hostname.  Contact your administrator to find
out what connection parameters you should use to connect (that is, what
host, username, and password to use).  Once you know the proper
parameters, you should be able to connect like this:

     shell> mysql -h HOST -u USER -p
     Enter password: ********

`host' and `user' represent the hostname where your MySQL server is
running and the username of your MySQL account.  Substitute appropriate
values for your setup.  The `********' represents your password; enter
it when `mysql' displays the `Enter password:' prompt.

If that works, you should see some introductory information followed by
a `mysql>' prompt:

     shell> mysql -h HOST -u USER -p
     Enter password: ********
     Welcome to the MySQL monitor.  Commands end with ; or \g.
     Your MySQL connection id is 25338 to server version: 4.0.14-log

     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

     mysql>

The prompt tells you that `mysql' is ready for you to enter commands.

Some MySQL installations allow users to connect as the anonymous
(unnamed) user to the server running on the local host.  If this is the
case on your machine, you should be able to connect to that server by
invoking `mysql' without any options:

     shell> mysql

After you have connected successfully, you can disconnect any time by
typing `QUIT' (or `\q') at the `mysql>' prompt:

     mysql> QUIT
     Bye

On Unix, you can also disconnect by pressing Control-D.

Most examples in the following sections assume that you are connected
to the server.  They indicate this by the `mysql>' prompt.

Entering Queries
================

Make sure that you are connected to the server, as discussed in the
previous section.  Doing so will not in itself select any database to
work with, but that's okay.  At this point, it's more important to find
out a little about how to issue queries than to jump right in creating
tables, loading data into them, and retrieving data from them.  This
section describes the basic principles of entering commands, using
several queries you can try out to familiarize yourself with how
`mysql' works.

Here's a simple command that asks the server to tell you its version
number and the current date.  Type it in as shown here following the
`mysql>' prompt and press Enter:

     mysql> SELECT VERSION(), CURRENT_DATE;
     +--------------+--------------+
     | VERSION()    | CURRENT_DATE |
     +--------------+--------------+
     | 3.22.20a-log | 1999-03-19   |
     +--------------+--------------+
     1 row in set (0.01 sec)
     mysql>

This query illustrates several things about `mysql':

   * A command normally consists of an SQL statement followed by a
     semicolon.  (There are some exceptions where a semicolon may be
     omitted.  `QUIT', mentioned earlier, is one of them.  We'll get to
     others later.)

   * When you issue a command, `mysql' sends it to the server for
     execution and displays the results, then prints another `mysql>'
     prompt to indicate that it is ready for another command.

   * `mysql' displays query output in tabular form (rows and columns).
     The first row contains labels for the columns.  The rows following
     are the query results.  Normally, column labels are the names of
     the columns you fetch from database tables.  If you're retrieving
     the value of an expression rather than a table column (as in the
     example just shown), `mysql' labels the column using the
     expression itself.

   * `mysql' shows how many rows were returned and how long the query
     took to execute, which gives you a rough idea of server
     performance.  These values are imprecise because they represent
     wall clock time (not CPU or machine time), and because they are
     affected by factors such as server load and network latency.  (For
     brevity, the "rows in set" line is not shown in the remaining
     examples in this chapter.)

Keywords may be entered in any lettercase.  The following queries are
equivalent:

     mysql> SELECT VERSION(), CURRENT_DATE;
     mysql> select version(), current_date;
     mysql> SeLeCt vErSiOn(), current_DATE;

Here's another query.  It demonstrates that you can use `mysql' as a
simple calculator:

     mysql> SELECT SIN(PI()/4), (4+1)*5;
     +-------------+---------+
     | SIN(PI()/4) | (4+1)*5 |
     +-------------+---------+
     |    0.707107 |      25 |
     +-------------+---------+

The queries shown thus far have been relatively short, single-line
statements.  You can even enter multiple statements on a single line.
Just end each one with a semicolon:

     mysql> SELECT VERSION(); SELECT NOW();
     +--------------+
     | VERSION()    |
     +--------------+
     | 3.22.20a-log |
     +--------------+

     +---------------------+
     | NOW()               |
     +---------------------+
     | 1999-03-19 00:15:33 |
     +---------------------+

A command need not be given all on a single line, so lengthy commands
that require several lines are not a problem.  `mysql' determines where
your statement ends by looking for the terminating semicolon, not by
looking for the end of the input line.  (In other words, `mysql'
accepts free-format input:  it collects input lines but does not
execute them until it sees the semicolon.)

Here's a simple multiple-line statement:

     mysql> SELECT
         -> USER()
         -> ,
         -> CURRENT_DATE;
     +--------------------+--------------+
     | USER()             | CURRENT_DATE |
     +--------------------+--------------+
     | joesmith@localhost | 1999-03-18   |
     +--------------------+--------------+

In this example, notice how the prompt changes from `mysql>' to `->'
after you enter the first line of a multiple-line query.  This is how
`mysql' indicates that it hasn't seen a complete statement and is
waiting for the rest.  The prompt is your friend, because it provides
valuable feedback.  If you use that feedback, you will always be aware
of what `mysql' is waiting for.

If you decide you don't want to execute a command that you are in the
process of entering, cancel it by typing `\c':

     mysql> SELECT
         -> USER()
         -> \c
     mysql>

Here, too, notice the prompt.  It switches back to `mysql>' after you
type `\c', providing feedback to indicate that `mysql' is ready for a
new command.

The following table shows each of the prompts you may see and
summarizes what they mean about the state that `mysql' is in:

*Prompt**Meaning*
`mysql>'Ready for new command.
`       Waiting for next line of multiple-line command.
->'
`       Waiting for next line, collecting a string that begins
'>'     with a single quote (`'').
`       Waiting for next line, collecting a string that begins
">'     with a double quote (`"').
`       Waiting for next line, collecting an identifier that
`>'     begins with a backtick (``').

Multiple-line statements commonly occur by accident when you intend to
issue a command on a single line, but forget the terminating semicolon.
In this case, `mysql' waits for more input:

     mysql> SELECT USER()
         ->

If this happens to you (you think you've entered a statement but the
only response is a `->' prompt), most likely `mysql' is waiting for the
semicolon.  If you don't notice what the prompt is telling you, you
might sit there for a while before realising what you need to do.
Enter a semicolon to complete the statement, and `mysql' will execute
it:

     mysql> SELECT USER()
         -> ;
     +--------------------+
     | USER()             |
     +--------------------+
     | joesmith@localhost |
     +--------------------+

The `'>' and `">' prompts occur during string collection.  In MySQL,
you can write strings surrounded by either `'' or `"' characters (for
example, `'hello'' or `"goodbye"'), and `mysql' lets you enter strings
that span multiple lines.  When you see a `'>' or `">' prompt, it means
that you've entered a line containing a string that begins with a `''
or `"' quote character, but have not yet entered the matching quote
that terminates the string.  That's fine if you really are entering a
multiple-line string, but how likely is that?  Not very.  More often,
the `'>' and `">' prompts indicate that you've inadvertantly left out a
quote character.  For example:

     mysql> SELECT * FROM my_table WHERE name = 'Smith AND age < 30;
         '>

If you enter this `SELECT' statement, then press Enter and wait for the
result, nothing will happen.  Instead of wondering why this query takes
so long, notice the clue provided by the `'>' prompt.  It tells you
that `mysql' expects to see the rest of an unterminated string.  (Do
you see the error in the statement?  The string `'Smith' is missing the
second quote.)

At this point, what do you do?  The simplest thing is to cancel the
command.  However, you cannot just type `\c' in this case, because
`mysql' interprets it as part of the string that it is collecting!
Instead, enter the closing quote character (so `mysql' knows you've
finished the string), then type `\c':

     mysql> SELECT * FROM my_table WHERE name = 'Smith AND age < 30;
         '> '\c
     mysql>

The prompt changes back to `mysql>', indicating that `mysql' is ready
for a new command.

The ``>' prompt is similar to th `'>' and `">' prompts, but indicates
that you have begun but not completed a backtick-quoted identifier.

It's important to know what the `'>', `">', and ``>' prompts signify,
because if you mistakenly enter an unterminated string, any further
lines you type will appear to be ignored by `mysql'--including a line
containing `QUIT'!  This can be quite confusing, especially if you
don't know that you need to supply the terminating quote before you can
cancel the current command.

Creating and Using a Database
=============================

Now that you know how to enter commands, it's time to access a database.

Suppose that you have several pets in your home (your menagerie) and
you'd like to keep track of various types of information about them.
You can do so by creating tables to hold your data and loading them
with the desired information.  Then you can answer different sorts of
questions about your animals by retrieving data from the tables.  This
section shows you how to:

   * Create a database

   * Create a table

   * Load data into the table

   * Retrieve data from the table in various ways

   * Use multiple tables

The menagerie database will be simple (deliberately), but it is not
difficult to think of real-world situations in which a similar type of
database might be used.  For example, a database like this could be
used by a farmer to keep track of livestock, or by a veterinarian to
keep track of patient records.  A menagerie distribution containing
some of the queries and sample data used in the following sections can
be obtained from the MySQL Web site.  It's available in either
compressed `tar' format
(`http://www.mysql.com/Downloads/Contrib/Examples/menagerie.tar.gz') or
Zip format
(`http://www.mysql.com/Downloads/Contrib/Examples/menagerie.zip').

Use the `SHOW' statement to find out what databases currently exist on
the server:

     mysql> SHOW DATABASES;
     +----------+
     | Database |
     +----------+
     | mysql    |
     | test     |
     | tmp      |
     +----------+

The list of databases is probably different on your machine, but the
`mysql' and `test' databases are likely to be among them.  The `mysql'
database is required because it describes user access privileges.  The
`test' database is often provided as a workspace for users to try
things out.

Note that you may not see all databases if you don't have the `SHOW
DATABASES' privilege. *Note `GRANT': GRANT.

If the `test' database exists, try to access it:

     mysql> USE test
     Database changed

Note that `USE', like `QUIT', does not require a semicolon.  (You can
terminate such statements with a semicolon if you like; it does no
harm.)  The `USE' statement is special in another way, too:  it must be
given on a single line.

You can use the `test' database (if you have access to it) for the
examples that follow, but anything you create in that database can be
removed by anyone else with access to it.  For this reason, you should
probably ask your MySQL administrator for permission to use a database
of your own.  Suppose that you want to call yours `menagerie'.  The
administrator needs to execute a command like this:

     mysql> GRANT ALL ON menagerie.* TO 'your_mysql_name'@'your_client_host';

where `your_mysql_name' is the MySQL username assigned to you and
`your_client_host' is the host from which you connect to the server.

Creating and Selecting a Database
---------------------------------

If the administrator creates your database for you when setting up your
permissions, you can begin using it.  Otherwise, you need to create it
yourself:

     mysql> CREATE DATABASE menagerie;

Under Unix, database names are case sensitive (unlike SQL keywords), so
you must always refer to your database as `menagerie', not as
`Menagerie', `MENAGERIE', or some other variant.  This is also true for
table names.  (Under Windows, this restriction does not apply, although
you must refer to databases and tables using the same lettercase
throughout a given query.)

Creating a database does not select it for use; you must do that
explicitly.  To make `menagerie' the current database, use this command:

     mysql> USE menagerie
     Database changed

Your database needs to be created only once, but you must select it for
use each time you begin a `mysql' session.  You can do this by issuing a
`USE' statement as shown in the example.  Alternatively, you can select
the database on the command line when you invoke `mysql'.  Just specify
its name after any connection parameters that you might need to
provide.  For example:

     shell> mysql -h HOST -u USER -p menagerie
     Enter password: ********

Note that `menagerie' is not your password on the command just shown.
If you want to supply your password on the command line after the `-p'
option, you must do so with no intervening space (for example, as
`-pmypassword', not as `-p mypassword').  However, putting your
password on the command line is not recommended, because doing so
exposes it to snooping by other users logged in on your machine.

Creating a Table
----------------

Creating the database is the easy part, but at this point it's empty, as
`SHOW TABLES' will tell you:

     mysql> SHOW TABLES;
     Empty set (0.00 sec)

The harder part is deciding what the structure of your database should
be: what tables you will need and what columns will be in each of them.

You'll want a table that contains a record for each of your pets.  This
can be called the `pet' table, and it should contain, as a bare minimum,
each animal's name.  Because the name by itself is not very
interesting, the table should contain other information.  For example,
if more than one person in your family keeps pets, you might want to
list each animal's owner.  You might also want to record some basic
descriptive information such as species and sex.

How about age?  That might be of interest, but it's not a good thing to
store in a database.  Age changes as time passes, which means you'd
have to update your records often.  Instead, it's better to store a
fixed value such as date of birth.  Then, whenever you need age, you
can calculate it as the difference between the current date and the
birth date.  MySQL provides functions for doing date arithmetic, so
this is not difficult.  Storing birth date rather than age has other
advantages, too:

   * You can use the database for tasks such as generating reminders
     for upcoming pet birthdays.  (If you think this type of query is
     somewhat silly, note that it is the same question you might ask in
     the context of a business database to identify clients to whom
     you'll soon need to send out birthday greetings, for that
     computer-assisted personal touch.)

   * You can calculate age in relation to dates other than the current
     date.  For example, if you store death date in the database, you
     can easily calculate how old a pet was when it died.

You can probably think of other types of information that would be
useful in the `pet' table, but the ones identified so far are
sufficient for now: name, owner, species, sex, birth, and death.

Use a `CREATE TABLE' statement to specify the layout of your table:

     mysql> CREATE TABLE pet (name VARCHAR(20), owner VARCHAR(20),
         -> species VARCHAR(20), sex CHAR(1), birth DATE, death DATE);

`VARCHAR' is a good choice for the `name', `owner', and `species'
columns because the column values will vary in length.  The lengths of
those columns need not all be the same, and need not be `20'.  You can
pick any length from `1' to `255', whatever seems most reasonable to
you.  (If you make a poor choice and it turns out later that you need a
longer field, MySQL provides an `ALTER TABLE' statement.)

Several types of values can be chosen to represent sex in animal
records, such as `'m'' and `'f'', or perhaps `'male'' and `'female''.
It's simplest to use the single characters `'m'' and `'f''.

The use of the `DATE' data type for the `birth' and `death' columns is
a fairly obvious choice.

Now that you have created a table, `SHOW TABLES' should produce some
output:

     mysql> SHOW TABLES;
     +---------------------+
     | Tables in menagerie |
     +---------------------+
     | pet                 |
     +---------------------+

To verify that your table was created the way you expected, use a
`DESCRIBE' statement:

     mysql> DESCRIBE pet;
     +---------+-------------+------+-----+---------+-------+
     | Field   | Type        | Null | Key | Default | Extra |
     +---------+-------------+------+-----+---------+-------+
     | name    | varchar(20) | YES  |     | NULL    |       |
     | owner   | varchar(20) | YES  |     | NULL    |       |
     | species | varchar(20) | YES  |     | NULL    |       |
     | sex     | char(1)     | YES  |     | NULL    |       |
     | birth   | date        | YES  |     | NULL    |       |
     | death   | date        | YES  |     | NULL    |       |
     +---------+-------------+------+-----+---------+-------+

You can use `DESCRIBE' any time, for example, if you forget the names of
the columns in your table or what types they have.

Loading Data into a Table
-------------------------

After creating your table, you need to populate it.  The `LOAD DATA' and
`INSERT' statements are useful for this.

Suppose that your pet records can be described as shown here.  (Observe
that MySQL expects dates in `'YYYY-MM-DD'' format; this may be
different from what you are used to.)

*name*  *owner* *species**sex**birth*        *death*
Fluffy  Harold  cat     f    1993-02-04
Claws   Gwen    cat     m    1994-03-17
Buffy   Harold  dog     f    1989-05-13
Fang    Benny   dog     m    1990-08-27
Bowser  Diane   dog     m    1979-08-31     1995-07-29
Chirpy  Gwen    bird    f    1998-09-11
WhistlerGwen    bird         1997-12-09
Slim    Benny   snake   m    1996-04-29

Because you are beginning with an empty table, an easy way to populate
it is to create a text file containing a row for each of your animals,
then load the contents of the file into the table with a single
statement.

You could create a text file `pet.txt' containing one record per line,
with values separated by tabs, and given in the order in which the
columns were listed in the `CREATE TABLE' statement.  For missing
values (such as unknown sexes or death dates for animals that are still
living), you can use `NULL' values.  To represent these in your text
file, use `\N' (backslash, capital-N).  For example, the record for
Whistler the bird would look like this (where the whitespace between
values is a single tab character):

*name*  *owner* *species**sex**birth*        *death*
`Whistler'`Gwen'  `bird'  `\N' `1997-12-09'   `\N'

To load the text file `pet.txt' into the `pet' table, use this command:

     mysql> LOAD DATA LOCAL INFILE '/path/pet.txt' INTO TABLE pet;

Note that if you created the file on Windows with an editor that uses
`\r\n' as a line terminator, you should use:

     mysql> LOAD DATA LOCAL INFILE '/path/pet.txt' INTO TABLE pet
         -> LINES TERMINATED BY '\r\n';

You can specify the column value separator and end of line marker
explicitly in the `LOAD DATA' statement if you wish, but the defaults
are tab and linefeed.  These are sufficient for the statement to read
the file `pet.txt' properly.

If the statement fails, it is likely that your MySQL installation does
not have local file capability enabled by default.  See *Note `LOAD
DATA LOCAL': LOAD DATA LOCAL for information on how to change this.

When you want to add new records one at a time, the `INSERT' statement
is useful.  In its simplest form, you supply values for each column, in
the order in which the columns were listed in the `CREATE TABLE'
statement.  Suppose that Diane gets a new hamster named Puffball.  You
could add a new record using an `INSERT' statement like this:

     mysql> INSERT INTO pet
         -> VALUES ('Puffball','Diane','hamster','f','1999-03-30',NULL);

Note that string and date values are specified as quoted strings here.
Also, with `INSERT', you can insert `NULL' directly to represent a
missing value.  You do not use `\N' like you do with `LOAD DATA'.

From this example, you should be able to see that there would be a lot
more typing involved to load your records initially using several
`INSERT' statements rather than a single `LOAD DATA' statement.

Retrieving Information from a Table
-----------------------------------

The `SELECT' statement is used to pull information from a table.  The
general form of the statement is:

     SELECT what_to_select
     FROM which_table
     WHERE conditions_to_satisfy;

`what_to_select' indicates what you want to see.  This can be a list of
columns, or `*' to indicate "all columns." `which_table' indicates the
table from which you want to retrieve data.  The `WHERE' clause is
optional.  If it's present, `conditions_to_satisfy' specifies
conditions that rows must satisfy to qualify for retrieval.

Selecting All Data
..................

The simplest form of `SELECT' retrieves everything from a table:

     mysql> SELECT * FROM pet;
     +----------+--------+---------+------+------------+------------+
     | name     | owner  | species | sex  | birth      | death      |
     +----------+--------+---------+------+------------+------------+
     | Fluffy   | Harold | cat     | f    | 1993-02-04 | NULL       |
     | Claws    | Gwen   | cat     | m    | 1994-03-17 | NULL       |
     | Buffy    | Harold | dog     | f    | 1989-05-13 | NULL       |
     | Fang     | Benny  | dog     | m    | 1990-08-27 | NULL       |
     | Bowser   | Diane  | dog     | m    | 1979-08-31 | 1995-07-29 |
     | Chirpy   | Gwen   | bird    | f    | 1998-09-11 | NULL       |
     | Whistler | Gwen   | bird    | NULL | 1997-12-09 | NULL       |
     | Slim     | Benny  | snake   | m    | 1996-04-29 | NULL       |
     | Puffball | Diane  | hamster | f    | 1999-03-30 | NULL       |
     +----------+--------+---------+------+------------+------------+

This form of `SELECT' is useful if you want to review your entire table,
for example, after you've just loaded it with your initial dataset.  For
example, you may happen to think that the birth date for Bowser doesn't
seem quite right.  Consulting your original pedigree papers, you find
that the correct birth year should be 1989, not 1979.

There are least a couple of ways to fix this:

   * Edit the file `pet.txt' to correct the error, then empty the table
     and reload it using `DELETE' and `LOAD DATA':

          mysql> DELETE FROM pet;
          mysql> LOAD DATA LOCAL INFILE 'pet.txt' INTO TABLE pet;

     However, if you do this, you must also re-enter the record for
     Puffball.

   * Fix only the erroneous record with an `UPDATE' statement:

          mysql> UPDATE pet SET birth = '1989-08-31' WHERE name = 'Bowser';

     The `UPDATE' changes only the record in question and does not
     require you to reload the table.

Selecting Particular Rows
.........................

As shown in the preceding section, it is easy to retrieve an entire
table.  Just omit the `WHERE' clause from the `SELECT' statement.  But
typically you don't want to see the entire table, particularly when it
becomes large.  Instead, you're usually more interested in answering a
particular question, in which case you specify some constraints on the
information you want.  Let's look at some selection queries in terms of
questions about your pets that they answer.

You can select only particular rows from your table.  For example, if
you want to verify the change that you made to Bowser's birth date,
select Bowser's record like this:

     mysql> SELECT * FROM pet WHERE name = 'Bowser';
     +--------+-------+---------+------+------------+------------+
     | name   | owner | species | sex  | birth      | death      |
     +--------+-------+---------+------+------------+------------+
     | Bowser | Diane | dog     | m    | 1989-08-31 | 1995-07-29 |
     +--------+-------+---------+------+------------+------------+

The output confirms that the year is correctly recorded now as 1989,
not 1979.

String comparisons normally are case-insensitive, so you can specify the
name as `'bowser'', `'BOWSER'', etc.  The query result will be the same.

You can specify conditions on any column, not just `name'.  For example,
if you want to know which animals were born after 1998, test the `birth'
column:

     mysql> SELECT * FROM pet WHERE birth >= '1998-1-1';
     +----------+-------+---------+------+------------+-------+
     | name     | owner | species | sex  | birth      | death |
     +----------+-------+---------+------+------------+-------+
     | Chirpy   | Gwen  | bird    | f    | 1998-09-11 | NULL  |
     | Puffball | Diane | hamster | f    | 1999-03-30 | NULL  |
     +----------+-------+---------+------+------------+-------+

You can combine conditions, for example, to locate female dogs:

     mysql> SELECT * FROM pet WHERE species = 'dog' AND sex = 'f';
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

The preceding query uses the `AND' logical operator.  There is also an
`OR' operator:

     mysql> SELECT * FROM pet WHERE species = 'snake' OR species = 'bird';
     +----------+-------+---------+------+------------+-------+
     | name     | owner | species | sex  | birth      | death |
     +----------+-------+---------+------+------------+-------+
     | Chirpy   | Gwen  | bird    | f    | 1998-09-11 | NULL  |
     | Whistler | Gwen  | bird    | NULL | 1997-12-09 | NULL  |
     | Slim     | Benny | snake   | m    | 1996-04-29 | NULL  |
     +----------+-------+---------+------+------------+-------+

`AND' and `OR' may be intermixed, although `AND' has higher precedence
than `OR'.  If you use both operators, it's a good idea to use
parentheses to indicate explicitly how conditions should be grouped:

     mysql> SELECT * FROM pet WHERE (species = 'cat' AND sex = 'm')
         -> OR (species = 'dog' AND sex = 'f');
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Claws | Gwen   | cat     | m    | 1994-03-17 | NULL  |
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

Selecting Particular Columns
............................

If you don't want to see entire rows from your table, just name the
columns in which you're interested, separated by commas.  For example,
if you want to know when your animals were born, select the `name' and
`birth' columns:

     mysql> SELECT name, birth FROM pet;
     +----------+------------+
     | name     | birth      |
     +----------+------------+
     | Fluffy   | 1993-02-04 |
     | Claws    | 1994-03-17 |
     | Buffy    | 1989-05-13 |
     | Fang     | 1990-08-27 |
     | Bowser   | 1989-08-31 |
     | Chirpy   | 1998-09-11 |
     | Whistler | 1997-12-09 |
     | Slim     | 1996-04-29 |
     | Puffball | 1999-03-30 |
     +----------+------------+

To find out who owns pets, use this query:

     mysql> SELECT owner FROM pet;
     +--------+
     | owner  |
     +--------+
     | Harold |
     | Gwen   |
     | Harold |
     | Benny  |
     | Diane  |
     | Gwen   |
     | Gwen   |
     | Benny  |
     | Diane  |
     +--------+

However, notice that the query simply retrieves the `owner' field from
each record, and some of them appear more than once.  To minimize the
output, retrieve each unique output record just once by adding the
keyword `DISTINCT':

     mysql> SELECT DISTINCT owner FROM pet;
     +--------+
     | owner  |
     +--------+
     | Benny  |
     | Diane  |
     | Gwen   |
     | Harold |
     +--------+

You can use a `WHERE' clause to combine row selection with column
selection.  For example, to get birth dates for dogs and cats only, use
this query:

     mysql> SELECT name, species, birth FROM pet
         -> WHERE species = 'dog' OR species = 'cat';
     +--------+---------+------------+
     | name   | species | birth      |
     +--------+---------+------------+
     | Fluffy | cat     | 1993-02-04 |
     | Claws  | cat     | 1994-03-17 |
     | Buffy  | dog     | 1989-05-13 |
     | Fang   | dog     | 1990-08-27 |
     | Bowser | dog     | 1989-08-31 |
     +--------+---------+------------+

Sorting Rows
............

You may have noticed in the preceding examples that the result rows are
displayed in no particular order.  It's often easier to examine query
output when the rows are sorted in some meaningful way.  To sort a
result, use an `ORDER BY' clause.

Here are animal birthdays, sorted by date:

     mysql> SELECT name, birth FROM pet ORDER BY birth;
     +----------+------------+
     | name     | birth      |
     +----------+------------+
     | Buffy    | 1989-05-13 |
     | Bowser   | 1989-08-31 |
     | Fang     | 1990-08-27 |
     | Fluffy   | 1993-02-04 |
     | Claws    | 1994-03-17 |
     | Slim     | 1996-04-29 |
     | Whistler | 1997-12-09 |
     | Chirpy   | 1998-09-11 |
     | Puffball | 1999-03-30 |
     +----------+------------+

On character type columns, sorting--like all other comparison
operations--is normally performed in a case-insensitive fashion.  This
means that the order will be undefined for columns that are identical
except for their case. You can force a case-sensitive sort for a column
by using the `BINARY' cast: `ORDER BY BINARY col_name'.

The default sort order is ascending, with smallest values first.  To
sort in reverse (descending) order, add the `DESC' keyword to the name
of the column you are sorting by:

     mysql> SELECT name, birth FROM pet ORDER BY birth DESC;
     +----------+------------+
     | name     | birth      |
     +----------+------------+
     | Puffball | 1999-03-30 |
     | Chirpy   | 1998-09-11 |
     | Whistler | 1997-12-09 |
     | Slim     | 1996-04-29 |
     | Claws    | 1994-03-17 |
     | Fluffy   | 1993-02-04 |
     | Fang     | 1990-08-27 |
     | Bowser   | 1989-08-31 |
     | Buffy    | 1989-05-13 |
     +----------+------------+

You can sort on multiple columns, and you can sort columns in different
directions.  For example, to sort by type of animal in ascending order,
then by birth date within animal type in descending order (youngest
animals first), use the following query:

     mysql> SELECT name, species, birth FROM pet
         -> ORDER BY species, birth DESC;
     +----------+---------+------------+
     | name     | species | birth      |
     +----------+---------+------------+
     | Chirpy   | bird    | 1998-09-11 |
     | Whistler | bird    | 1997-12-09 |
     | Claws    | cat     | 1994-03-17 |
     | Fluffy   | cat     | 1993-02-04 |
     | Fang     | dog     | 1990-08-27 |
     | Bowser   | dog     | 1989-08-31 |
     | Buffy    | dog     | 1989-05-13 |
     | Puffball | hamster | 1999-03-30 |
     | Slim     | snake   | 1996-04-29 |
     +----------+---------+------------+

Note that the `DESC' keyword applies only to the column name immediately
preceding it (`birth'); it does not affect the `species' column sort
order.

Date Calculations
.................

MySQL provides several functions that you can use to perform
calculations on dates, for example, to calculate ages or extract parts
of dates.

To determine how many years old each of your pets is, compute the
difference in the year part of the current date and the birth date, then
subtract one if the current date occurs earlier in the calendar year
than the birth date.  The following query shows, for each pet, the
birth date, the current date, and the age in years.

     mysql> SELECT name, birth, CURDATE(),
         -> (YEAR(CURDATE())-YEAR(birth))
         -> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
         -> AS age
         -> FROM pet;
     +----------+------------+------------+------+
     | name     | birth      | CURDATE()  | age  |
     +----------+------------+------------+------+
     | Fluffy   | 1993-02-04 | 2003-08-19 |   10 |
     | Claws    | 1994-03-17 | 2003-08-19 |    9 |
     | Buffy    | 1989-05-13 | 2003-08-19 |   14 |
     | Fang     | 1990-08-27 | 2003-08-19 |   12 |
     | Bowser   | 1989-08-31 | 2003-08-19 |   13 |
     | Chirpy   | 1998-09-11 | 2003-08-19 |    4 |
     | Whistler | 1997-12-09 | 2003-08-19 |    5 |
     | Slim     | 1996-04-29 | 2003-08-19 |    7 |
     | Puffball | 1999-03-30 | 2003-08-19 |    4 |
     +----------+------------+------------+------+

Here, `YEAR()' pulls out the year part of a date and `RIGHT()' pulls
off the rightmost five characters that represent the `MM-DD' (calendar
year) part of the date.  The part of the expression that compares the
`MM-DD' values evaluates to 1 or 0, which adjusts the year difference
down a year if `CURDATE()' occurs earlier in the year than `birth'.
The full expression is somewhat ungainly, so an alias (`age') is used
to make the output column label more meaningful.

The query works, but the result could be scanned more easily if the rows
were presented in some order.  This can be done by adding an `ORDER BY
name' clause to sort the output by name:

     mysql> SELECT name, birth, CURDATE(),
         -> (YEAR(CURDATE())-YEAR(birth))
         -> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
         -> AS age
         -> FROM pet ORDER BY name;
     +----------+------------+------------+------+
     | name     | birth      | CURDATE()  | age  |
     +----------+------------+------------+------+
     | Bowser   | 1989-08-31 | 2003-08-19 |   13 |
     | Buffy    | 1989-05-13 | 2003-08-19 |   14 |
     | Chirpy   | 1998-09-11 | 2003-08-19 |    4 |
     | Claws    | 1994-03-17 | 2003-08-19 |    9 |
     | Fang     | 1990-08-27 | 2003-08-19 |   12 |
     | Fluffy   | 1993-02-04 | 2003-08-19 |   10 |
     | Puffball | 1999-03-30 | 2003-08-19 |    4 |
     | Slim     | 1996-04-29 | 2003-08-19 |    7 |
     | Whistler | 1997-12-09 | 2003-08-19 |    5 |
     +----------+------------+------------+------+

To sort the output by `age' rather than `name', just use a different
`ORDER BY' clause:

     mysql> SELECT name, birth, CURDATE(),
         -> (YEAR(CURDATE())-YEAR(birth))
         -> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
         -> AS age
         -> FROM pet ORDER BY age;
     +----------+------------+------------+------+
     | name     | birth      | CURDATE()  | age  |
     +----------+------------+------------+------+
     | Chirpy   | 1998-09-11 | 2003-08-19 |    4 |
     | Puffball | 1999-03-30 | 2003-08-19 |    4 |
     | Whistler | 1997-12-09 | 2003-08-19 |    5 |
     | Slim     | 1996-04-29 | 2003-08-19 |    7 |
     | Claws    | 1994-03-17 | 2003-08-19 |    9 |
     | Fluffy   | 1993-02-04 | 2003-08-19 |   10 |
     | Fang     | 1990-08-27 | 2003-08-19 |   12 |
     | Bowser   | 1989-08-31 | 2003-08-19 |   13 |
     | Buffy    | 1989-05-13 | 2003-08-19 |   14 |
     +----------+------------+------------+------+

A similar query can be used to determine age at death for animals that
have died.  You determine which animals these are by checking whether
the `death' value is `NULL'.  Then, for those with non-`NULL' values,
compute the difference between the `death' and `birth' values:

     mysql> SELECT name, birth, death,
         -> (YEAR(death)-YEAR(birth)) - (RIGHT(death,5)<RIGHT(birth,5))
         -> AS age
         -> FROM pet WHERE death IS NOT NULL ORDER BY age;
     +--------+------------+------------+------+
     | name   | birth      | death      | age  |
     +--------+------------+------------+------+
     | Bowser | 1989-08-31 | 1995-07-29 |    5 |
     +--------+------------+------------+------+

The query uses `death IS NOT NULL' rather than `death <> NULL' because
`NULL' is a special value that cannot be compared using the usual
comparison operators.  This is discussed later.  *Note Working with
`NULL': Working with NULL.

What if you want to know which animals have birthdays next month?  For
this type of calculation, year and day are irrelevant; you simply want
to extract the month part of the `birth' column.  MySQL provides several
date-part extraction functions, such as `YEAR()', `MONTH()', and
`DAYOFMONTH()'.  `MONTH()' is the appropriate function here.  To see
how it works, run a simple query that displays the value of both
`birth' and `MONTH(birth)':

     mysql> SELECT name, birth, MONTH(birth) FROM pet;
     +----------+------------+--------------+
     | name     | birth      | MONTH(birth) |
     +----------+------------+--------------+
     | Fluffy   | 1993-02-04 |            2 |
     | Claws    | 1994-03-17 |            3 |
     | Buffy    | 1989-05-13 |            5 |
     | Fang     | 1990-08-27 |            8 |
     | Bowser   | 1989-08-31 |            8 |
     | Chirpy   | 1998-09-11 |            9 |
     | Whistler | 1997-12-09 |           12 |
     | Slim     | 1996-04-29 |            4 |
     | Puffball | 1999-03-30 |            3 |
     +----------+------------+--------------+

Finding animals with birthdays in the upcoming month is easy, too.
Suppose that the current month is April.  Then the month value is `4'
and you look for animals born in May (month `5') like this:

     mysql> SELECT name, birth FROM pet WHERE MONTH(birth) = 5;
     +-------+------------+
     | name  | birth      |
     +-------+------------+
     | Buffy | 1989-05-13 |
     +-------+------------+

There is a small complication if the current month is December.  You
don't just add one to the month number (`12') and look for animals born
in month `13', because there is no such month.  Instead, you look for
animals born in January (month `1').

You can even write the query so that it works no matter what the current
month is.  That way you don't have to use a particular month number in
the query.  `DATE_ADD()' allows you to add a time interval to a given
date.  If you add a month to the value of `CURDATE()', then extract the
month part with `MONTH()', the result produces the month in which to
look for birthdays:

     mysql> SELECT name, birth FROM pet
         -> WHERE MONTH(birth) = MONTH(DATE_ADD(CURDATE(),INTERVAL 1 MONTH));

A different way to accomplish the same task is to add `1' to get the
next month after the current one (after using the modulo function
(`MOD') to wrap around the month value to `0' if it is currently `12'):

     mysql> SELECT name, birth FROM pet
         -> WHERE MONTH(birth) = MOD(MONTH(CURDATE()), 12) + 1;

Note that `MONTH' returns a number between `1' and `12'. And
`MOD(something,12)' returns a number between `0' and `11'. So the
addition has to be after the `MOD()', otherwise we would go from
November (`11') to January (`1').

Working with `NULL' Values
..........................

The `NULL' value can be surprising until you get used to it.
Conceptually, `NULL' means missing value or unknown value and it is
treated somewhat differently than other values.  To test for `NULL',
you cannot use the arithmetic comparison operators such as `=', `<', or
`<>'.  To demonstrate this for yourself, try the following query:

     mysql> SELECT 1 = NULL, 1 <> NULL, 1 < NULL, 1 > NULL;
     +----------+-----------+----------+----------+
     | 1 = NULL | 1 <> NULL | 1 < NULL | 1 > NULL |
     +----------+-----------+----------+----------+
     |     NULL |      NULL |     NULL |     NULL |
     +----------+-----------+----------+----------+

Clearly you get no meaningful results from these comparisons.  Use the
`IS NULL' and `IS NOT NULL' operators instead:

     mysql> SELECT 1 IS NULL, 1 IS NOT NULL;
     +-----------+---------------+
     | 1 IS NULL | 1 IS NOT NULL |
     +-----------+---------------+
     |         0 |             1 |
     +-----------+---------------+

Note that in MySQL, `0' or `NULL' means false and anything else means
true. The default truth value from a boolean operation is `1'.

This special treatment of `NULL' is why, in the previous section, it
was necessary to determine which animals are no longer alive using
`death IS NOT NULL' instead of `death <> NULL'.

Two `NULL' values are regarded as equal in a `GROUP BY'.

When doing an `ORDER BY', `NULL' values are presented first if you do
`ORDER BY ... ASC' and last if you do `ORDER BY ... DESC'.

Note that MySQL 4.0.2 to 4.0.10 incorrectly always sorts `NULL' values
first regardless of the sort direction.

Pattern Matching
................

MySQL provides standard SQL pattern matching as well as a form of
pattern matching based on extended regular expressions similar to those
used by Unix utilities such as `vi', `grep', and `sed'.

SQL pattern matching allows you to use `_' to match any single
character and `%' to match an arbitrary number of characters (including
zero characters).  In MySQL, SQL patterns are case-insensitive by
default.  Some examples are shown here.  Note that you do not use `='
or `<>' when you use SQL patterns; use the `LIKE' or `NOT LIKE'
comparison operators instead.

To find names beginning with `b':

     mysql> SELECT * FROM pet WHERE name LIKE 'b%';
     +--------+--------+---------+------+------------+------------+
     | name   | owner  | species | sex  | birth      | death      |
     +--------+--------+---------+------+------------+------------+
     | Buffy  | Harold | dog     | f    | 1989-05-13 | NULL       |
     | Bowser | Diane  | dog     | m    | 1989-08-31 | 1995-07-29 |
     +--------+--------+---------+------+------------+------------+

To find names ending with `fy':

     mysql> SELECT * FROM pet WHERE name LIKE '%fy';
     +--------+--------+---------+------+------------+-------+
     | name   | owner  | species | sex  | birth      | death |
     +--------+--------+---------+------+------------+-------+
     | Fluffy | Harold | cat     | f    | 1993-02-04 | NULL  |
     | Buffy  | Harold | dog     | f    | 1989-05-13 | NULL  |
     +--------+--------+---------+------+------------+-------+

To find names containing a `w':

     mysql> SELECT * FROM pet WHERE name LIKE '%w%';
     +----------+-------+---------+------+------------+------------+
     | name     | owner | species | sex  | birth      | death      |
     +----------+-------+---------+------+------------+------------+
     | Claws    | Gwen  | cat     | m    | 1994-03-17 | NULL       |
     | Bowser   | Diane | dog     | m    | 1989-08-31 | 1995-07-29 |
     | Whistler | Gwen  | bird    | NULL | 1997-12-09 | NULL       |
     +----------+-------+---------+------+------------+------------+

To find names containing exactly five characters, use five instances of
the `_' pattern character:

     mysql> SELECT * FROM pet WHERE name LIKE '_____';
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Claws | Gwen   | cat     | m    | 1994-03-17 | NULL  |
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

The other type of pattern matching provided by MySQL uses extended
regular expressions.  When you test for a match for this type of
pattern, use the `REGEXP' and `NOT REGEXP' operators (or `RLIKE' and
`NOT RLIKE', which are synonyms).

Some characteristics of extended regular expressions are:

   * `.' matches any single character.

   * A character class `[...]' matches any character within the
     brackets.  For example, `[abc]' matches `a', `b', or `c'.  To name
     a range of characters, use a dash.  `[a-z]' matches any letter,
     whereas `[0-9]' matches any digit.

   * `*' matches zero or more instances of the thing preceding it.  For
     example, `x*' matches any number of `x' characters, `[0-9]*'
     matches any number of digits, and `.*' matches any number of
     anything.

   * A `REGEXP' pattern match succeed if the pattern matches anywhere
     in the value being tested.  (This differs from a `LIKE' pattern
     match, which succeeds only if the pattern matches the entire
     value.)

   * To anchor a pattern so that it must match the beginning or end of
     the value being tested, use `^' at the beginning or `$' at the end
     of the pattern.

To demonstrate how extended regular expressions work, the `LIKE' queries
shown previously are rewritten here to use `REGEXP'.

To find names beginning with `b', use `^' to match the beginning of the
name:

     mysql> SELECT * FROM pet WHERE name REGEXP '^b';
     +--------+--------+---------+------+------------+------------+
     | name   | owner  | species | sex  | birth      | death      |
     +--------+--------+---------+------+------------+------------+
     | Buffy  | Harold | dog     | f    | 1989-05-13 | NULL       |
     | Bowser | Diane  | dog     | m    | 1989-08-31 | 1995-07-29 |
     +--------+--------+---------+------+------------+------------+

Prior to MySQL Version 3.23.4, `REGEXP' is case sensitive, and the
previous query will return no rows. In this case, to match either
lowercase or uppercase `b', use this query instead:

     mysql> SELECT * FROM pet WHERE name REGEXP '^[bB]';

From MySQL 3.23.4 on, if you really want to force a `REGEXP' comparison
to be case sensitive, use the `BINARY' keyword to make one of the
strings a binary string. This query will match only lowercase `b' at
the beginning of a name:

     mysql> SELECT * FROM pet WHERE name REGEXP BINARY '^b';

To find names ending with `fy', use `$' to match the end of the name:

     mysql> SELECT * FROM pet WHERE name REGEXP 'fy$';
     +--------+--------+---------+------+------------+-------+
     | name   | owner  | species | sex  | birth      | death |
     +--------+--------+---------+------+------------+-------+
     | Fluffy | Harold | cat     | f    | 1993-02-04 | NULL  |
     | Buffy  | Harold | dog     | f    | 1989-05-13 | NULL  |
     +--------+--------+---------+------+------------+-------+

To find names containing a `w', use this query:

     mysql> SELECT * FROM pet WHERE name REGEXP 'w';
     +----------+-------+---------+------+------------+------------+
     | name     | owner | species | sex  | birth      | death      |
     +----------+-------+---------+------+------------+------------+
     | Claws    | Gwen  | cat     | m    | 1994-03-17 | NULL       |
     | Bowser   | Diane | dog     | m    | 1989-08-31 | 1995-07-29 |
     | Whistler | Gwen  | bird    | NULL | 1997-12-09 | NULL       |
     +----------+-------+---------+------+------------+------------+

Because a regular expression pattern matches if it occurs anywhere in
the value, it is not necessary in the previous query to put a wildcard
on either side of the pattern to get it to match the entire value like
it would be if you used an SQL pattern.

To find names containing exactly five characters, use `^' and `$' to
match the beginning and end of the name, and five instances of `.' in
between:

     mysql> SELECT * FROM pet WHERE name REGEXP '^.....$';
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Claws | Gwen   | cat     | m    | 1994-03-17 | NULL  |
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

You could also write the previous query using the `{n}'
"repeat-`n'-times" operator:

     mysql> SELECT * FROM pet WHERE name REGEXP '^.{5}$';
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Claws | Gwen   | cat     | m    | 1994-03-17 | NULL  |
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

Counting Rows
.............

Databases are often used to answer the question, "How often does a
certain type of data occur in a table?"  For example, you might want to
know how many pets you have, or how many pets each owner has, or you
might want to perform various kinds of census operations on your
animals.

Counting the total number of animals you have is the same question as
"How many rows are in the `pet' table?" because there is one record per
pet.  `COUNT(*)' counts the number of rows, so the query to count your
animals looks like this:

     mysql> SELECT COUNT(*) FROM pet;
     +----------+
     | COUNT(*) |
     +----------+
     |        9 |
     +----------+

Earlier, you retrieved the names of the people who owned pets.  You can
use `COUNT()' if you want to find out how many pets each owner has:

     mysql> SELECT owner, COUNT(*) FROM pet GROUP BY owner;
     +--------+----------+
     | owner  | COUNT(*) |
     +--------+----------+
     | Benny  |        2 |
     | Diane  |        2 |
     | Gwen   |        3 |
     | Harold |        2 |
     +--------+----------+

Note the use of `GROUP BY' to group together all records for each
`owner'.  Without it, all you get is an error message:

     mysql> SELECT owner, COUNT(*) FROM pet;
     ERROR 1140: Mixing of GROUP columns (MIN(),MAX(),COUNT()...)
     with no GROUP columns is illegal if there is no GROUP BY clause

`COUNT()' and `GROUP BY' are useful for characterizing your data in
various ways.  The following examples show different ways to perform
animal census operations.

Number of animals per species:

     mysql> SELECT species, COUNT(*) FROM pet GROUP BY species;
     +---------+----------+
     | species | COUNT(*) |
     +---------+----------+
     | bird    |        2 |
     | cat     |        2 |
     | dog     |        3 |
     | hamster |        1 |
     | snake   |        1 |
     +---------+----------+

Number of animals per sex:

     mysql> SELECT sex, COUNT(*) FROM pet GROUP BY sex;
     +------+----------+
     | sex  | COUNT(*) |
     +------+----------+
     | NULL |        1 |
     | f    |        4 |
     | m    |        4 |
     +------+----------+

(In this output, `NULL' indicates that the sex is unknown.)

Number of animals per combination of species and sex:

     mysql> SELECT species, sex, COUNT(*) FROM pet GROUP BY species, sex;
     +---------+------+----------+
     | species | sex  | COUNT(*) |
     +---------+------+----------+
     | bird    | NULL |        1 |
     | bird    | f    |        1 |
     | cat     | f    |        1 |
     | cat     | m    |        1 |
     | dog     | f    |        1 |
     | dog     | m    |        2 |
     | hamster | f    |        1 |
     | snake   | m    |        1 |
     +---------+------+----------+

You need not retrieve an entire table when you use `COUNT()'.  For
example, the previous query, when performed just on dogs and cats,
looks like this:

     mysql> SELECT species, sex, COUNT(*) FROM pet
         -> WHERE species = 'dog' OR species = 'cat'
         -> GROUP BY species, sex;
     +---------+------+----------+
     | species | sex  | COUNT(*) |
     +---------+------+----------+
     | cat     | f    |        1 |
     | cat     | m    |        1 |
     | dog     | f    |        1 |
     | dog     | m    |        2 |
     +---------+------+----------+

Or, if you wanted the number of animals per sex only for known-sex
animals:

     mysql> SELECT species, sex, COUNT(*) FROM pet
         -> WHERE sex IS NOT NULL
         -> GROUP BY species, sex;
     +---------+------+----------+
     | species | sex  | COUNT(*) |
     +---------+------+----------+
     | bird    | f    |        1 |
     | cat     | f    |        1 |
     | cat     | m    |        1 |
     | dog     | f    |        1 |
     | dog     | m    |        2 |
     | hamster | f    |        1 |
     | snake   | m    |        1 |
     +---------+------+----------+

Using More Than one Table
.........................

The `pet' table keeps track of which pets you have.  If you want to
record other information about them, such as events in their lives like
visits to the vet or when litters are born, you need another table.
What should this table look like? It needs:

   * To contain the pet name so you know which animal each event
     pertains to.

   * A date so you know when the event occurred.

   * A field to describe the event.

   * An event type field, if you want to be able to categorize events.

Given these considerations, the `CREATE TABLE' statement for the
`event' table might look like this:

     mysql> CREATE TABLE event (name VARCHAR(20), date DATE,
         -> type VARCHAR(15), remark VARCHAR(255));

As with the `pet' table, it's easiest to load the initial records by
creating a tab-delimited text file containing the information:

*name*      *date*      *type*      *remark*
Fluffy      1995-05-15  litter      4 kittens, 3 female, 1
                                    male
Buffy       1993-06-23  litter      5 puppies, 2 female, 3
                                    male
Buffy       1994-06-19  litter      3 puppies, 3 female
Chirpy      1999-03-21  vet         needed beak straightened
Slim        1997-08-03  vet         broken rib
Bowser      1991-10-12  kennel
Fang        1991-10-12  kennel
Fang        1998-08-28  birthday    Gave him a new chew toy
Claws       1998-03-17  birthday    Gave him a new flea
                                    collar
Whistler    1998-12-09  birthday    First birthday

Load the records like this:

     mysql> LOAD DATA LOCAL INFILE 'event.txt' INTO TABLE event;

Based on what you've learned from the queries you've run on the `pet'
table, you should be able to perform retrievals on the records in the
`event' table; the principles are the same.  But when is the `event'
table by itself insufficient to answer questions you might ask?

Suppose that you want to find out the ages at which each pet had its
litters. We saw earlier how to calculate ages from two dates.  The
litter date of the mother is in the `event' table, but to calculate her
age on that date you need her birth date, which is stored in the `pet'
table.  This means the query requires both tables:

     mysql> SELECT pet.name,
         -> (YEAR(date)-YEAR(birth)) - (RIGHT(date,5)<RIGHT(birth,5)) AS age,
         -> remark
         -> FROM pet, event
         -> WHERE pet.name = event.name AND type = 'litter';
     +--------+------+-----------------------------+
     | name   | age  | remark                      |
     +--------+------+-----------------------------+
     | Fluffy |    2 | 4 kittens, 3 female, 1 male |
     | Buffy  |    4 | 5 puppies, 2 female, 3 male |
     | Buffy  |    5 | 3 puppies, 3 female         |
     +--------+------+-----------------------------+

There are several things to note about this query:

   * The `FROM' clause lists two tables because the query needs to pull
     information from both of them.

   * When combining (joining) information from multiple tables, you
     need to specify how records in one table can be matched to records
     in the other.  This is easy because they both have a `name'
     column.  The query uses `WHERE' clause to match up records in the
     two tables based on the `name' values.

   * Because the `name' column occurs in both tables, you must be
     specific about which table you mean when referring to the column.
     This is done by prepending the table name to the column name.

You need not have two different tables to perform a join.  Sometimes it
is useful to join a table to itself, if you want to compare records in
a table to other records in that same table.  For example, to find
breeding pairs among your pets, you can join the `pet' table with
itself to produce candidate pairs of males and females of like species:

     mysql> SELECT p1.name, p1.sex, p2.name, p2.sex, p1.species
         -> FROM pet AS p1, pet AS p2
         -> WHERE p1.species = p2.species AND p1.sex = 'f' AND p2.sex = 'm';
     +--------+------+--------+------+---------+
     | name   | sex  | name   | sex  | species |
     +--------+------+--------+------+---------+
     | Fluffy | f    | Claws  | m    | cat     |
     | Buffy  | f    | Fang   | m    | dog     |
     | Buffy  | f    | Bowser | m    | dog     |
     +--------+------+--------+------+---------+

In this query, we specify aliases for the table name in order to refer
to the columns and keep straight which instance of the table each
column reference is associated with.

Getting Information About Databases and Tables
==============================================

What if you forget the name of a database or table, or what the
structure of a given table is (for example, what its columns are
called)?  MySQL addresses this problem through several statements that
provide information about the databases and tables it supports.

You have already seen `SHOW DATABASES', which lists the databases
managed by the server.  To find out which database is currently
selected, use the `DATABASE()' function:

     mysql> SELECT DATABASE();
     +------------+
     | DATABASE() |
     +------------+
     | menagerie  |
     +------------+

If you haven't selected any database yet, the result is `NULL' (or the
empty string before MySQL 4.1.1).

To find out what tables the current database contains (for example, when
you're not sure about the name of a table), use this command:

     mysql> SHOW TABLES;
     +---------------------+
     | Tables in menagerie |
     +---------------------+
     | event               |
     | pet                 |
     +---------------------+

If you want to find out about the structure of a table, the `DESCRIBE'
command is useful; it displays information about each of a table's
columns:

     mysql> DESCRIBE pet;
     +---------+-------------+------+-----+---------+-------+
     | Field   | Type        | Null | Key | Default | Extra |
     +---------+-------------+------+-----+---------+-------+
     | name    | varchar(20) | YES  |     | NULL    |       |
     | owner   | varchar(20) | YES  |     | NULL    |       |
     | species | varchar(20) | YES  |     | NULL    |       |
     | sex     | char(1)     | YES  |     | NULL    |       |
     | birth   | date        | YES  |     | NULL    |       |
     | death   | date        | YES  |     | NULL    |       |
     +---------+-------------+------+-----+---------+-------+

`Field' indicates the column name, `Type' is the data type for the
column, `NULL' indicates whether the column can contain `NULL' values,
`Key' indicates whether the column is indexed, and `Default' specifies
the column's default value.

If you have indexes on a table, `SHOW INDEX FROM TBL_NAME' produces
information about them.

Using `mysql' in Batch Mode
===========================

In the previous sections, you used `mysql' interactively to enter
queries and view the results.  You can also run `mysql' in batch mode.
To do this, put the commands you want to run in a file, then tell
`mysql' to read its input from the file:

     shell> mysql < BATCH-FILE

If you are running `mysql' under Windows and have some special
characters in the file that cause problems, you can do this:

     C:\> mysql -e "source BATCH-FILE"

If you need to specify connection parameters on the command line, the
command might look like this:

     shell> mysql -h HOST -u USER -p < BATCH-FILE
     Enter password: ********

When you use `mysql' this way, you are creating a script file, then
executing the script.

If you want the script to continue even if some of the statements in it
produce errors, you should use the `--force' command-line option.

Why use a script?  Here are a few reasons:

   * If you run a query repeatedly (say, every day or every week),
     making it a script allows you to avoid retyping it each time you
     execute it.

   * You can generate new queries from existing ones that are similar
     by copying and editing script files.

   * Batch mode can also be useful while you're developing a query,
     particularly for multiple-line commands or multiple-statement
     sequences of commands.  If you make a mistake, you don't have to
     retype everything.  Just edit your script to correct the error,
     then tell `mysql' to execute it again.

   * If you have a query that produces a lot of output, you can run the
     output through a pager rather than watching it scroll off the top
     of your screen:

          shell> mysql < BATCH-FILE | more

   * You can catch the output in a file for further processing:

          shell> mysql < BATCH-FILE > mysql.out

   * You can distribute your script to other people so they can run the
     commands, too.

   * Some situations do not allow for interactive use, for example,
     when you run a query from a `cron' job.  In this case, you must
     use batch mode.

The default output format is different (more concise) when you run
`mysql' in batch mode than when you use it interactively.  For example,
the output of `SELECT DISTINCT species FROM pet' looks like this when
`mysql' is run interactively:

     +---------+
     | species |
     +---------+
     | bird    |
     | cat     |
     | dog     |
     | hamster |
     | snake   |
     +---------+

In batch mode, the output looks like this instead:

     species
     bird
     cat
     dog
     hamster
     snake

If you want to get the interactive output format in batch mode, use
`mysql -t'.  To echo to the output the commands that are executed, use
`mysql -vvv'.

You can also use scripts from the `mysql' prompt by using the `source'
or `\.' command:

     mysql> source filename;
     mysql> \. filename

Examples of Common Queries
==========================

Here are examples of how to solve some common problems with MySQL.

Some of the examples use the table `shop' to hold the price of each
article (item number) for certain traders (dealers).  Supposing that
each trader has a single fixed price per article, then (`article',
`dealer') is a primary key for the records.

Start the command-line tool `mysql' and select a database:

     shell> mysql your-database-name

(In most MySQL installations, you can use the database name `test').

You can create and populate the example table with these statements:

     mysql> CREATE TABLE shop (
         -> article INT(4) UNSIGNED ZEROFILL DEFAULT '0000' NOT NULL,
         -> dealer  CHAR(20)                 DEFAULT ''     NOT NULL,
         -> price   DOUBLE(16,2)             DEFAULT '0.00' NOT NULL,
         -> PRIMARY KEY(article, dealer));
     mysql> INSERT INTO shop VALUES
         -> (1,'A',3.45),(1,'B',3.99),(2,'A',10.99),(3,'B',1.45),
         -> (3,'C',1.69),(3,'D',1.25),(4,'D',19.95);

After issuing the statements, the table should have the following
contents:

     mysql> SELECT * FROM shop;
     +---------+--------+-------+
     | article | dealer | price |
     +---------+--------+-------+
     |    0001 | A      |  3.45 |
     |    0001 | B      |  3.99 |
     |    0002 | A      | 10.99 |
     |    0003 | B      |  1.45 |
     |    0003 | C      |  1.69 |
     |    0003 | D      |  1.25 |
     |    0004 | D      | 19.95 |
     +---------+--------+-------+

The Maximum Value for a Column
------------------------------

"What's the highest item number?"

     SELECT MAX(article) AS article FROM shop;

     +---------+
     | article |
     +---------+
     |       4 |
     +---------+

The Row Holding the Maximum of a Certain Column
-----------------------------------------------

"Find number, dealer, and price of the most expensive article."

In standard SQL (and as of MySQL 4.1), this is easily done with a
subquery:

     SELECT article, dealer, price
     FROM   shop
     WHERE  price=(SELECT MAX(price) FROM shop);

In MySQL versions prior to 4.1, just do it in two steps:

  1. Get the maximum price value from the table with a `SELECT'
     statement.
          mysql> SELECT MAX(price) FROM shop;
          +------------+
          | MAX(price) |
          +------------+
          |      19.95 |
          +------------+

  2. Using the value 19.95 shown by the previous query to be the maximum
     article price, write a query to locate and display the
     corresponding record:
          mysql> SELECT article, dealer, price
              -> FROM   shop
              -> WHERE  price=19.95;
          +---------+--------+-------+
          | article | dealer | price |
          +---------+--------+-------+
          |    0004 | D      | 19.95 |
          +---------+--------+-------+

Another solution is to sort all rows descending by price and only get
the first row using the MySQL-specific `LIMIT' clause:

     SELECT article, dealer, price
     FROM   shop
     ORDER BY price DESC
     LIMIT 1;

Note:  If there were several most expensive articles, each with a price
of 19.95, the `LIMIT' solution would show only one of them!

Maximum of Column per Group
---------------------------

"What's the highest price per article?"

     SELECT article, MAX(price) AS price
     FROM   shop
     GROUP BY article

     +---------+-------+
     | article | price |
     +---------+-------+
     |    0001 |  3.99 |
     |    0002 | 10.99 |
     |    0003 |  1.69 |
     |    0004 | 19.95 |
     +---------+-------+

The Rows Holding the Group-wise Maximum of a Certain Field
----------------------------------------------------------

"For each article, find the dealer or dealers with the most expensive
price."

In standard SQL (and as of MySQL 4.1), the problem can be solved with a
subquery like this:

     SELECT article, dealer, price
     FROM   shop s1
     WHERE  price=(SELECT MAX(s2.price)
                   FROM shop s2
                   WHERE s1.article = s2.article);

In MySQL versions prior to 4.1, it's best do it in several steps:

  1. Get the list of (article,maxprice) pairs.

  2. For each article, get the corresponding rows that have the stored
     maximum price.

This can easily be done with a temporary table and a join:

     CREATE TEMPORARY TABLE tmp (
             article INT(4) UNSIGNED ZEROFILL DEFAULT '0000' NOT NULL,
             price   DOUBLE(16,2)             DEFAULT '0.00' NOT NULL);

     LOCK TABLES shop READ;

     INSERT INTO tmp SELECT article, MAX(price) FROM shop GROUP BY article;

     SELECT shop.article, dealer, shop.price FROM shop, tmp
     WHERE shop.article=tmp.article AND shop.price=tmp.price;

     UNLOCK TABLES;

     DROP TABLE tmp;

If you don't use a `TEMPORARY' table, you must also lock the `tmp'
table.

"Can it be done with a single query?"

Yes, but only by using a quite inefficient trick called the "MAX-CONCAT
trick":

     SELECT article,
            SUBSTRING( MAX( CONCAT(LPAD(price,6,'0'),dealer) ), 7) AS dealer,
       0.00+LEFT(      MAX( CONCAT(LPAD(price,6,'0'),dealer) ), 6) AS price
     FROM   shop
     GROUP BY article;

     +---------+--------+-------+
     | article | dealer | price |
     +---------+--------+-------+
     |    0001 | B      |  3.99 |
     |    0002 | A      | 10.99 |
     |    0003 | C      |  1.69 |
     |    0004 | D      | 19.95 |
     +---------+--------+-------+

The last example can be made a bit more efficient by doing the
splitting of the concatenated column in the client.

Using User Variables
--------------------

You can use MySQL user variables to remember results without having to
store them in temporary variables in the client.  *Note Variables::.

For example, to find the articles with the highest and lowest price you
can do this:

     mysql> SELECT @min_price:=MIN(price),@max_price:=MAX(price) FROM shop;
     mysql> SELECT * FROM shop WHERE price=@min_price OR price=@max_price;
     +---------+--------+-------+
     | article | dealer | price |
     +---------+--------+-------+
     |    0003 | D      |  1.25 |
     |    0004 | D      | 19.95 |
     +---------+--------+-------+

Using Foreign Keys
------------------

In MySQL 3.23.44 and up, `InnoDB' tables support checking of foreign
key constraints. *Note `InnoDB': InnoDB.  See also *Note ANSI diff
Foreign Keys::.

You don't actually need foreign keys to join two tables.  For table
types other than `InnoDB', the only things MySQL currently doesn't do
are 1) `CHECK' to make sure that the keys you use really exist in the
table or tables you're referencing and 2) automatically delete rows
from a table with a foreign key definition. Using your keys to join
tables will work just fine:

     CREATE TABLE person (
         id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
         name CHAR(60) NOT NULL,
         PRIMARY KEY (id)
     );

     CREATE TABLE shirt (
         id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
         style ENUM('t-shirt', 'polo', 'dress') NOT NULL,
         color ENUM('red', 'blue', 'orange', 'white', 'black') NOT NULL,
         owner SMALLINT UNSIGNED NOT NULL REFERENCES person(id),
         PRIMARY KEY (id)
     );


     INSERT INTO person VALUES (NULL, 'Antonio Paz');

     INSERT INTO shirt VALUES
     (NULL, 'polo', 'blue', LAST_INSERT_ID()),
     (NULL, 'dress', 'white', LAST_INSERT_ID()),
     (NULL, 't-shirt', 'blue', LAST_INSERT_ID());


     INSERT INTO person VALUES (NULL, 'Lilliana Angelovska');

     INSERT INTO shirt VALUES
     (NULL, 'dress', 'orange', LAST_INSERT_ID()),
     (NULL, 'polo', 'red', LAST_INSERT_ID()),
     (NULL, 'dress', 'blue', LAST_INSERT_ID()),
     (NULL, 't-shirt', 'white', LAST_INSERT_ID());


     SELECT * FROM person;
     +----+---------------------+
     | id | name                |
     +----+---------------------+
     |  1 | Antonio Paz         |
     |  2 | Lilliana Angelovska |
     +----+---------------------+

     SELECT * FROM shirt;
     +----+---------+--------+-------+
     | id | style   | color  | owner |
     +----+---------+--------+-------+
     |  1 | polo    | blue   |     1 |
     |  2 | dress   | white  |     1 |
     |  3 | t-shirt | blue   |     1 |
     |  4 | dress   | orange |     2 |
     |  5 | polo    | red    |     2 |
     |  6 | dress   | blue   |     2 |
     |  7 | t-shirt | white  |     2 |
     +----+---------+--------+-------+


     SELECT s.* FROM person p, shirt s
      WHERE p.name LIKE 'Lilliana%'
        AND s.owner = p.id
        AND s.color <> 'white';

     +----+-------+--------+-------+
     | id | style | color  | owner |
     +----+-------+--------+-------+
     |  4 | dress | orange |     2 |
     |  5 | polo  | red    |     2 |
     |  6 | dress | blue   |     2 |
     +----+-------+--------+-------+

Searching on Two Keys
---------------------

An `OR' using a single key is well optimized, as is the handling of
`AND'.

The one tricky case is that of searching on two different keys combined
with `OR':

     SELECT field1_index, field2_index FROM test_table
     WHERE field1_index = '1' OR  field2_index = '1'

This case is optimized from MySQL 5.0.0.  *Note Index Merge
optimization::.

In MySQL 4.0 and up, you can also solve the problem efficiently by
using a `UNION' that combines the output of two separate `SELECT'
statements.  *Note UNION::.

Each `SELECT' searches only one key and can be optimized:

     SELECT field1_index, field2_index
         FROM test_table WHERE field1_index = '1'
     UNION
     SELECT field1_index, field2_index
         FROM test_table WHERE field2_index = '1';

Prior to MySQL 4.0, you can achieve the same effect by using a
`TEMPORARY' table and separate `SELECT' statements.  This type of
optimization is also very good if you are using very complicated
queries where the SQL server does the optimizations in the wrong order.

     CREATE TEMPORARY TABLE tmp
     SELECT field1_index, field2_index
         FROM test_table WHERE field1_index = '1';
     INSERT INTO tmp
     SELECT field1_index, field2_index
         FROM test_table WHERE field2_index = '1';
     SELECT * from tmp;
     DROP TABLE tmp;

This method of solving the problem is in effect a `UNION' of two
queries.

Calculating Visits Per Day
--------------------------

The following example shows how you can use the bit group functions to
calculate the number of days per month a user has visited a Web page.

     CREATE TABLE t1 (year YEAR(4), month INT(2) UNSIGNED ZEROFILL,
                  day INT(2) UNSIGNED ZEROFILL);
     INSERT INTO t1 VALUES(2000,1,1),(2000,1,20),(2000,1,30),(2000,2,2),
                 (2000,2,23),(2000,2,23);

The example table contains year-month-day values representing visits by
users to the page. To determine how many different days in each month
these visits occur, use this query:

     SELECT year,month,BIT_COUNT(BIT_OR(1<<day)) AS days FROM t1
            GROUP BY year,month;

Which returns:

     +------+-------+------+
     | year | month | days |
     +------+-------+------+
     | 2000 |    01 |    3 |
     | 2000 |    02 |    2 |
     +------+-------+------+

The query calculates how many different days appear in the table for
each year/month combination, with automatic removal of duplicate
entries.

Using `AUTO_INCREMENT'
----------------------

The `AUTO_INCREMENT' attribute can be used to generate a unique
identity for new rows:

     CREATE TABLE animals (
                  id MEDIUMINT NOT NULL AUTO_INCREMENT,
                  name CHAR(30) NOT NULL,
                  PRIMARY KEY (id)
                  );
     INSERT INTO animals (name) VALUES ('dog'),('cat'),('penguin'),
                                       ('lax'),('whale'),('ostrich');
     SELECT * FROM animals;

Which returns:

     +----+---------+
     | id | name    |
     +----+---------+
     |  1 | dog     |
     |  2 | cat     |
     |  3 | penguin |
     |  4 | lax     |
     |  5 | whale   |
     |  6 | ostrich |
     +----+---------+

You can retrieve the most recent `AUTO_INCREMENT' value with the
`LAST_INSERT_ID()' SQL function or the `mysql_insert_id()' C API
function. These functions are connection-specific, so their return value
is not affected by another connection also doing inserts.

Note: For a multiple-row insert, `LAST_INSERT_ID()'/`mysql_insert_id()'
will actually return the `AUTO_INCREMENT' key from the *first* of the
inserted rows.  This allows multiple-row inserts to be reproduced
correctly on other servers in a replication setup.

For `MyISAM' and `BDB' tables you can specify `AUTO_INCREMENT' on a
secondary column in a multiple-column index.  In this case, the
generated value for the `AUTO_INCREMENT' column is calculated as
`MAX(auto_increment_column)+1 WHERE prefix=given-prefix'.  This is
useful when you want to put data into ordered groups.

     CREATE TABLE animals (
                  grp ENUM('fish','mammal','bird') NOT NULL,
                  id MEDIUMINT NOT NULL AUTO_INCREMENT,
                  name CHAR(30) NOT NULL,
                  PRIMARY KEY (grp,id)
                  );
     INSERT INTO animals (grp,name) VALUES('mammal','dog'),('mammal','cat'),
                       ('bird','penguin'),('fish','lax'),('mammal','whale'),
                       ('bird','ostrich');
     SELECT * FROM animals ORDER BY grp,id;

Which returns:

     +--------+----+---------+
     | grp    | id | name    |
     +--------+----+---------+
     | fish   |  1 | lax     |
     | mammal |  1 | dog     |
     | mammal |  2 | cat     |
     | mammal |  3 | whale   |
     | bird   |  1 | penguin |
     | bird   |  2 | ostrich |
     +--------+----+---------+

Note that in this case (when the `AUTO_INCREMENT' column is part of a
multiple-column index), `AUTO_INCREMENT' values will be reused if you
delete the row with the biggest `AUTO_INCREMENT' value in any group.
This happens even for `MyISAM' tables, for which `AUTO_INCREMENT'
values normally are not reused.)

Queries from the Twin Project
=============================

At Analytikerna and Lentus, we have been doing the systems and field
work for a big research project. This project is a collaboration
between the Institute of Environmental Medicine at Karolinska
Institutet Stockholm and the Section on Clinical Research in Aging and
Psychology at the University of Southern California.

The project involves a screening part where all twins in Sweden older
than 65 years are interviewed by telephone. Twins who meet certain
criteria are passed on to the next stage. In this latter stage, twins
who want to participate are visited by a doctor/nurse team. Some of the
examinations include physical and neuropsychological examination,
laboratory testing, neuroimaging, psychological status assessment, and
family history collection. In addition, data are collected on medical
and environmental risk factors.

More information about Twin studies can be found at:
`http://www.mep.ki.se/twinreg/index_en.html'

The latter part of the project is administered with a Web interface
written using Perl and MySQL.

Each night all data from the interviews is moved into a MySQL database.

Find All Non-distributed Twins
------------------------------

The following query is used to determine who goes into the second part
of the project:

     SELECT
         CONCAT(p1.id, p1.tvab) + 0 AS tvid,
         CONCAT(p1.christian_name, ' ', p1.surname) AS Name,
         p1.postal_code AS Code,
         p1.city AS City,
         pg.abrev AS Area,
         IF(td.participation = 'Aborted', 'A', ' ') AS A,
         p1.dead AS dead1,
         l.event AS event1,
         td.suspect AS tsuspect1,
         id.suspect AS isuspect1,
         td.severe AS tsevere1,
         id.severe AS isevere1,
         p2.dead AS dead2,
         l2.event AS event2,
         h2.nurse AS nurse2,
         h2.doctor AS doctor2,
         td2.suspect AS tsuspect2,
         id2.suspect AS isuspect2,
         td2.severe AS tsevere2,
         id2.severe AS isevere2,
         l.finish_date
     FROM
         twin_project AS tp
         /* For Twin 1 */
         LEFT JOIN twin_data AS td ON tp.id = td.id
                   AND tp.tvab = td.tvab
         LEFT JOIN informant_data AS id ON tp.id = id.id
                   AND tp.tvab = id.tvab
         LEFT JOIN harmony AS h ON tp.id = h.id
                   AND tp.tvab = h.tvab
         LEFT JOIN lentus AS l ON tp.id = l.id
                   AND tp.tvab = l.tvab
         /* For Twin 2 */
         LEFT JOIN twin_data AS td2 ON p2.id = td2.id
                   AND p2.tvab = td2.tvab
         LEFT JOIN informant_data AS id2 ON p2.id = id2.id
                   AND p2.tvab = id2.tvab
         LEFT JOIN harmony AS h2 ON p2.id = h2.id
                   AND p2.tvab = h2.tvab
         LEFT JOIN lentus AS l2 ON p2.id = l2.id
                   AND p2.tvab = l2.tvab,
         person_data AS p1,
         person_data AS p2,
         postal_groups AS pg
     WHERE
         /* p1 gets main twin and p2 gets his/her twin. */
         /* ptvab is a field inverted from tvab */
         p1.id = tp.id AND p1.tvab = tp.tvab AND
         p2.id = p1.id AND p2.ptvab = p1.tvab AND
         /* Just the sceening survey */
         tp.survey_no = 5 AND
         /* Skip if partner died before 65 but allow emigration (dead=9) */
         (p2.dead = 0 OR p2.dead = 9 OR
          (p2.dead = 1 AND
           (p2.death_date = 0 OR
            (((TO_DAYS(p2.death_date) - TO_DAYS(p2.birthday)) / 365)
             >= 65))))
         AND
         (
         /* Twin is suspect */
         (td.future_contact = 'Yes' AND td.suspect = 2) OR
         /* Twin is suspect - Informant is Blessed */
         (td.future_contact = 'Yes' AND td.suspect = 1
                                    AND id.suspect = 1) OR
         /* No twin - Informant is Blessed */
         (ISNULL(td.suspect) AND id.suspect = 1
                             AND id.future_contact = 'Yes') OR
         /* Twin broken off - Informant is Blessed */
         (td.participation = 'Aborted'
          AND id.suspect = 1 AND id.future_contact = 'Yes') OR
         /* Twin broken off - No inform - Have partner */
         (td.participation = 'Aborted' AND ISNULL(id.suspect)
                                       AND p2.dead = 0))
         AND
         l.event = 'Finished'
         /* Get at area code */
         AND SUBSTRING(p1.postal_code, 1, 2) = pg.code
         /* Not already distributed */
         AND (h.nurse IS NULL OR h.nurse=00 OR h.doctor=00)
         /* Has not refused or been aborted */
         AND NOT (h.status = 'Refused' OR h.status = 'Aborted'
         OR h.status = 'Died' OR h.status = 'Other')
     ORDER BY
         tvid;

Some explanations:
`CONCAT(p1.id, p1.tvab) + 0 AS tvid'
     We want to sort on the concatenated `id' and `tvab' in numerical
     order. Adding `0' to the result causes MySQL to treat the result
     as a number.

column `id'
     This identifies a pair of twins. It is a key in all tables.

column `tvab'
     This identifies a twin in a pair. It has a value of `1' or `2'.

column `ptvab'
     This is an inverse of `tvab'. When `tvab' is `1' this is `2', and
     vice versa. It exists to save typing and to make it easier for
     MySQL to optimize the query.

This query demonstrates, among other things, how to do lookups on a
table from the same table with a join (`p1' and `p2'). In the example,
this is used to check whether a twin's partner died before the age of
65. If so, the row is not returned.

All of the above exist in all tables with twin-related information. We
have a key on both `id,tvab' (all tables), and `id,ptvab'
(`person_data') to make queries faster.

On our production machine (A 200MHz UltraSPARC), this query returns
about 150-200 rows and takes less than one second.

The current number of records in the tables used in the query:
*Table*            *Rows*
`person_data'      71074
`lentus'           5291
`twin_project'     5286
`twin_data'        2012
`informant_data'   663
`harmony'          381
`postal_groups'    100

Show a Table of Twin Pair Status
--------------------------------

Each interview ends with a status code called `event'. The query shown
here is used to display a table over all twin pairs combined by event.
This indicates in how many pairs both twins are finished, in how many
pairs one twin is finished and the other refused, and so on.

     SELECT
             t1.event,
             t2.event,
             COUNT(*)
     FROM
             lentus AS t1,
             lentus AS t2,
             twin_project AS tp
     WHERE
             /* We are looking at one pair at a time */
             t1.id = tp.id
             AND t1.tvab=tp.tvab
             AND t1.id = t2.id
             /* Just the sceening survey */
             AND tp.survey_no = 5
             /* This makes each pair only appear once */
             AND t1.tvab='1' AND t2.tvab='2'
     GROUP BY
             t1.event, t2.event;

Using MySQL with Apache
=======================

There are programs that let you authenticate your users from a MySQL
database and also let you write your log files into a MySQL table.

You can change the Apache logging format to be easily readable by MySQL
by putting the following into the Apache configuration file:

     LogFormat \
             "\"%h\",%{%Y%m%d%H%M%S}t,%>s,\"%b\",\"%{Content-Type}o\",  \
             \"%U\",\"%{Referer}i\",\"%{User-Agent}i\""

To load a log file in that format into MySQL, you can use a statement
something like this:

     LOAD DATA INFILE '/LOCAL/ACCESS_LOG' INTO TABLE TBL_NAME
     FIELDS TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"' ESCAPED BY '\\'

The named table should be created to have columns that correspond to
those that the `LogFormat' line writes to the log file.

Using MySQL Programs
********************

This chapter provides a brief overview of the programs provided by
MySQL AB and discusses how to specify options when you run these
programs.  Most programs have options that are specific to their own
operation, but the syntax for specifying options is similar for all of
them. Later chapters provide more detailed descriptions of individual
programs, including which options they recognize.

Overview of MySQL Programs
==========================

MySQL AB provides several types of programs:

The MYSQL server and server startup scripts:
        * `mysqld' is the MySQL server

        * `mysqld_safe', `mysql.server', and `mysqld_multi' are server
          startup scripts

        * `mysql_install_db' initializes the data directory and the
          initial databases

     These programs are discussed further in *Note MySQL Database
     Administration::.

Client programs that access the server:
        * `mysql' is a command-line client for executing SQL statements
          interactively or in batch mode

        * `mysqlcc' (MySQL Control Center) is an interactive graphical
          tool for executing SQL statements and administration

        * `mysqladmin' is an administrative client

        * `mysqlcheck' performs table maintenance operations

        * `mysqldump' and `mysqlhotcopy' make database backups

        * `mysqlimport' imports data files

        * `mysqlshow' displays information about databases and tables

     These programs are discussed further in *Note Client-Side
     Scripts::.

Utility programs that operate independently of the server:
        * `myisamchk' performs table maintenance operations

        * `myisampack' produces compressed, read-only tables

        * `mysqlbinlog' is a tool for processing binary log files

        * `perror' displays error code meanings

     `myisamchk' is discussed further in *Note MySQL Database
     Administration::.  The other programs are further in *Note
     Client-Side Scripts::.

Most MySQL distributions include all of these programs, except for those
programs that are platform-specific. (For example, the server startup
scripts are not used on Windows.) The exception is that RPM
distributions are more specialized. There is one RPM for the server,
another for the client programs, and so forth. If you appear to be
missing one or more programs, see *Note Installing:: for information on
types of distributions and what they contain.  It may be that you need
to install something else.

Invoking MySQL Programs
=======================

To invoke a MySQL program at the command line (that is, from your shell
or command prompt), enter the program name followed by any options or
other arguments needed to instruct the program what you want it to do.
The following commands show some sample program invocations. "`shell>'"
represents the prompt for your command interpreter; it is not part of
what you type.  The particular prompt you will see depends on your
command interpreter.  Typical prompts are `$' for `sh' or `bash', `%'
for `csh' or `tcsh', and `C:\>' for Windows `command.com' or `cmd.exe'.

     shell> mysql test
     shell> mysqladmin extended-status variables
     shell> mysqlshow --help
     shell> mysqldump --user=root personnel

Arguments that begin with a dash are option arguments. They typically
specify the type of connection a program should make to the server or
affect its operational mode. Options have a syntax that is described in
*Note Program Options::.

Non-option arguments (arguments with no leading dash) provide additional
information to the program. For example, the `mysql' program interprets
the first non-option argument as a database name, so the command `mysql
test' indicates that you want to use the `test' database.

Later sections that describe individual programs indicate which options
a program understands and describe the meaning of any additional
non-option arguments.

Some options are common to a number of programs. The most common of
these are the `--host', `--user', and `--password' options that specify
connection parameters. They indicate the host where the MySQL server is
running, and the username and password of your MySQL account. All MySQL
client programs understand these options; they allow you to specify
which server to connect to and the account to use on that server.

You may find it necessary to invoke MySQL programs using the pathname
to the `bin' directory in which they are installed. This is likely to
be the case if you get a "program not found" error whenever you attempt
to run a MySQL program from any directory other than the `bin'
directory.  To make it more convenient to use MySQL, you can add the
pathname of the `bin' directory to your `PATH' environment variable
setting. Then to run a program you need only type its name, not its
entire pathname.

Consult the documentation for your command interpreter for instructions
on setting your `PATH'. The syntax for setting environment variables is
interpreter-specific.

Specifying Program Options
==========================

You can provide options for MySQL programs in several ways:

   * On the command line following the program name. This is most
     common for options that apply to a specific invocation of the
     program.

   * In an option file that the program reads when it starts. This is
     common for options that you want the program to use each time it
     runs.

   * In environment variables. These are useful for options that you
     want to apply each time the program runs, although in practice
     option files are used more commonly for this purpose.  (*Note
     Multiple Unix servers:: discusses one situation in which
     environment variables can be very helpful. It describes a handy
     technique that uses such variables to specify the TCP/IP port
     number and Unix socket file for both the server and client
     programs.)


MySQL programs determine which options are given first by examining
environment variables, then option files, and then the command line.
If an option is specified multiple times, the last occurrence takes
precedence.  This means that environment variables have the lowest
precedence and command-line options the highest.

You can take advantage of the way that MySQL programs process options by
specifying the default values for a program's options in an option
file. Then you need not type them each time you run the program, but
can override the defaults if necessary by using command-line options.

Using Options on the Command Line
---------------------------------

Program options specified on the command line follow these rules:

   * Options are given after the command name.

   * An option argument begins with one dash or two dashes, depending
     on whether it has a short name or a long name. Many options have
     both forms.  For example, `-?' and `--help' are the short and long
     forms of the option that instructs a MySQL program to display a
     help message.

   * Option names are case sensitive.  `-v' and `-V' are both legal and
     have different meanings. (They are the corresponding short forms
     of the `--verbose' and `--version' options.)

   * Some options take a value following the option name.  For example,
     `-h localhost' or `--host=localhost' indicate the MySQL server
     host to a client program.  The option value tells the program the
     name of the host where the MySQL server is running.

   * For a long option that takes a value, separate the option name and
     the value by an `=' sign.  For a short option that takes a value,
     the option value can immediately follow the option letter, or
     there can be a space between.  (`-hlocalhost' and `-h localhost'
     are equivalent.)  An exception to this rule is the option for
     specifying your MySQL password.  This option can be given in long
     form as `--password=pass_val' or as `--password'. In the latter
     case (with no password value given), the program will prompt you
     for the password.  The password option also may be given in short
     form as `-ppass_val' or as `-p'. However, for the short form, if
     the password value is given, it must follow the option letter with
     _no intervening space_. The reason for this is that if a space
     follows the option letter, the program has no way to tell whether
     a following argument is supposed to be the password value or some
     other kind of argument.  Consequently, the following two commands
     have two completely different meanings:

          shell> mysql -ptest
          shell> mysql -p test

     The first command instructs `mysql' to use a password value of
     `test', but specifies no default database.  The second instructs
     `mysql' to prompt for the password value and to use `test' as the
     default database.


MySQL 4.0 introduced some additional flexibility in the way you specify
options. These changes were made in MySQL 4.0.2. Some of them relate to
the way you specify options that have "enabled" and "disabled" states,
and to the use of options that might be present in one version of MySQL
but not another.  Those capabilities are discussed in this section.
Another change pertains to the way you use options to set program
variables.  *Note Program variables:: discusses that topic further.

Some options control behavior that can be turned on or off. For example,
the `mysql' client supports a `--column-names' option that determines
whether or not to display a row of column names at the beginning of
query results. By default, this option is enabled. However, you may
want to disable it in some instances, such as when sending the output
of `mysql' into another program that expects to see only data and not
an initial header line.

To disable column names, you can specify the option using any of these
forms:

     --disable-column-names
     --skip-column-names
     --column-names=0

The `--disable' and `--skip' prefixes and the `=0' suffix all have the
same effect: They turn the option off.

The "enabled" form of the option may be specified in any of these ways:

     --column-names
     --enable-column-names
     --column-names=1

Another change to option processing introduced in MySQL 4.0 is that you
can use the `--loose' prefix for command-line options. If an option is
prefixed by `--loose', the program will not exit with an error if it
does not recognize the option, but instead will issue only a warning:

     shell> mysql --loose-no-such-option
     mysql: WARNING: unknown option '--no-such-option'

The `--loose' prefix can be useful when you run programs from multiple
installations of MySQL on the same machine, at least if all the
versions are as recent as 4.0.2.  This prefix is particularly useful
when you list options in an option file.  An option that may not be
recognized by all versions of a program can be given using the `--loose'
prefix (or `loose' in an option file). Versions of the program that do
not recognize the option will issue a warning and ignore it. This
strategy requires that versions involved be 4.0.2 or later, because
earlier versions know nothing of the `--loose' convention.

Using Option Files
------------------

MySQL programs can read startup options from option files (also
sometimes called configuration files).  Option files provide a
convenient way to specify commonly used options so that they need not
be entered on the command line each time you run a program.  Option
file capability is available from MySQL 3.22 on.

The following programs support option files: `myisamchk', `myisampack',
`mysql', `mysql.server', `mysqladmin', `mysqlbinlog', `mysqlcc',
`mysqlcheck', `mysqld_safe', `mysqldump', `mysqld', `mysqlhotcopy',
`mysqlimport', and `mysqlshow'.

On Windows, MySQL programs read startup options from the following
files:

*Filename*             *Purpose*
`WINDIR\my.ini'        Global options
`C:\my.cnf'            Global options

WINDIR represents the location of your Windows directory.  This is
commonly `C:\Windows' or `C:\WinNT'.  You can determine its exact
location from the value of the `WINDIR' environment variable using the
following command:

     C:\> echo %WINDIR%

On Unix, MySQL programs read startup options from the following files:

*Filename*             *Purpose*
`/etc/my.cnf'          Global options
`DATADIR/my.cnf'       Server-specific options
`defaults-extra-file'  The file specified with
                       `--defaults-extra-file=PATH', if any
`~/.my.cnf'            User-specific options

DATADIR represents the location of the MySQL data directory. Typically
this is `/usr/local/mysql/data' for a binary installation or
`/usr/local/var' for a source installation.  Note that this is the data
directory location that was specified at configuration time, not the
one specified with `--datadir' when `mysqld' starts.  Use of
`--datadir' at runtime has no effect on where the server looks for
option files, because it looks for them before processing any
command-line arguments.

MySQL looks for option files in the order just described and reads any
that exist. If an option file that you want to use does not exist,
create it with a plain text editor.  If multiple option files exist, an
option specified in a file read later takes precedence over the same
option specified in a file read earlier.

Any long option that may be given on the command line when running a
MySQL program can be given in an option file as well.  To get the list
of available options for a program, run it with the `--help' option.

The syntax for specifying options in an option file is similar to
command-line syntax, except that you omit the leading two dashes. For
example, `--quick' or `--host=localhost' on the command line should be
specified as `quick' or `host=localhost' in an option file.  To specify
an option of the form `--loose-opt_name' in an option file, write it as
`loose-opt_name'.

Empty lines in option files are ignored. Non-empty lines can take any
of the following forms:

`#COMMENT'
`;COMMENT'
     Comment lines start with `#' or `;'. As of MySQL 4.0.14, a
     `#'-comment can start in the middle of a line as well.

`[GROUP]'
     GROUP is the name of the program or group for which you want to set
     options.  After a group line, any OPT_NAME or `set-variable' lines
     apply to the named group until the end of the option file or
     another group line is given.

`OPT_NAME'
     This is equivalent to `--OPT_NAME' on the command line.

`OPT_NAME=VALUE'
     This is equivalent to `--OPT_NAME=VALUE' on the command line.  In
     an option file, you can have spaces around the `=' character,
     something that is not true on the command line.  As of MySQL
     4.0.16, you can quote the value with double quotes or single
     quotes.  This is useful if the value contains a `#' comment
     character or whitespace.

`set-variable = VAR_NAME=VALUE'
     Set the program variable VAR_NAME to the given value.  This is
     equivalent to `--set-variable=VAR_NAME=VALUE' on the command line.
     Spaces are allowed around the first `=' character but not around
     the second.  This syntax is deprecated as of MySQL 4.0.  See *Note
     Program variables:: for more information on setting program
     variables.

Leading and trailing blanks are automatically deleted from option names
and values.  You may use the escape sequences `\b', `\t', `\n', `\r',
`\\', and `\s' in option values to represent the backspace, tab,
newline, carriage return, and space characters.

On Windows, if an option value represents a pathname, you should
specify the value using `/' rather than `\' as the pathname separator.
If you use `\', you must double it as `\\', because `\' is the escape
character in MySQL.

If an option group name is the same as a program name, options in the
group apply specifically to that program.

The `[client]' option group is read by all client programs (but not by
`mysqld'). This allows you to specify options that apply to every
client. For example, `[client]' is the perfect group to use to specify
the password that you use to connect to the server.  (But make sure that
the option file is readable and writable only by yourself, so that other
people cannot find out your password.) Be sure not to put an option in
the `[client]' group unless it is recognized by _all_ client programs
that you use. Programs that do not understand the option will quit after
displaying an error message if you try to run them.

As of MySQL 4.0.14, if you want to create option groups that should be
read only by one specific `mysqld' server release series, you can do
this by using groups with names of `[mysqld-4.0]', `[mysqld-4.1]', and
so forth. The following group indicates that the `--new' option should
be used only by MySQL servers with 4.0.x version numbers:

     [mysqld-4.0]
     new

Here is a typical global option file:

     [client]
     port=3306
     socket=/tmp/mysql.sock

     [mysqld]
     port=3306
     socket=/tmp/mysql.sock
     key_buffer_size=16M
     max_allowed_packet=8M

     [mysqldump]
     quick

The preceding option file uses `VAR_NAME=VALUE' syntax for the lines
that set the `key_buffer_size' and `max_allowed_packet' variables.
Prior to MySQL 4.0.2, you would need to use `set-variable' syntax
instead (described earlier in this section).

Here is a typical user option file:

     [client]
     # The following password will be sent to all standard MySQL clients
     password="my_password"

     [mysql]
     no-auto-rehash
     set-variable = connect_timeout=2

     [mysqlhotcopy]
     interactive-timeout

This option file uses `set-variable' syntax to set the
`connect_timeout' variable. For MySQL 4.0.2 and up, you can also set
the variable using just `connect_timeout=2'.

If you have a source distribution, you will find sample option files
named `my-XXXX.cnf' in the `support-files' directory.  If you have a
binary distribution, look in the `support-files' directory under your
MySQL installation directory (typically `C:\mysql' on Windows or
`/usr/local/mysql' on Unix).  Currently there are sample option files
for small, medium, large, and very large systems. To experiment with
one of these files, copy it to `C:\my.cnf' on Windows or to `.my.cnf'
in your home directory on Unix.

*Note*: On Windows, the `.cnf' option file extension might not be
displayed.

All MySQL programs that support option files handle the following
command-line options:

`--no-defaults'
     Don't read any option files.

`--print-defaults'
     Print the program name and all options that it will get from
     option files.

`--defaults-file=PATH_NAME'
     Use only the given option file. PATH_NAME is the full pathname to
     the file.

`--defaults-extra-file=PATH_NAME'
     Read this option file after the global option file but before the
     user option file. PATH_NAME is the full pathname to the file.

To work properly, each of these options must immediately follow the
command name on the command line, with the exception that
`--print-defaults' may be used immediately after `--defaults-file' or
`--defaults-extra-file'.

In shell scripts, you can use the `my_print_defaults' program to parse
option files. The following example shows the output that
`my_print_defaults' might produce when asked to show the options found
in the `[client]' and `[mysql]' groups:

     shell> my_print_defaults client mysql
     --port=3306
     --socket=/tmp/mysql.sock
     --no-auto-rehash

Note for developers:  Option file handling is implemented in the C
client library simply by processing all matching options (that is,
options in the appropriate group) before any command-line arguments.
This works nicely for programs that use the last instance of an option
that is specified multiple times. If you have a C or C++ program that
handles multiply specified options this way but doesn't read option
files, you need add only two lines to give it that capability.  Check
the source code of any of the standard MySQL clients to see how to do
this.

Several other language interfaces to MySQL are based on the C client
library, and some of them provide a way to access option file contents.
These include Perl and Python. See the documentation for your preferred
interface for details.

Using Environment Variables to Specify Options
----------------------------------------------

To specify an option using an environment variable, set the variable
using the syntax appropriate for your comment processor. For example,
on Windows or NetWare, you can set the `USER' variable to specify your
MySQL account name.  To do so, use this syntax:

     SET USER=YOUR_NAME

The syntax on Unix depends on your shell. Suppose that you want to
specify the TCP/IP port number using the `MYSQL_TCP_PORT' variable. The
syntax for Bourne shell and variants (`sh', `bash', `zsh', etc.) is:

     MYSQL_TCP_PORT=3306

For `csh' and `tcsh', use this syntax:

     setenv MYSQL_TCP_PORT 3306

The commands to set environment variables can be executed at your
command prompt to take effect immediately. These settings persist until
you log out.  To have the settings take effect each time you log in,
place the appropriate command or commands in a startup file that your
command interpreter reads each time it starts. Typical startup files are
`AUTOEXEC.BAT' for Windows, `.bash_profile' for `bash', or `.tcshrc'
for `tcsh'. Consult the documentation for your command interpreter for
specific details.

*Note Environment variables:: lists all environment variables that
affect MySQL program operation.

Using Options to Set Program Variables
--------------------------------------

Many MySQL programs have internal variables that can be set at runtime.
As of MySQL 4.0.2, program variables are set the same way as any other
long option that takes a value.  For example, `mysql' has a
`max_allowed_packet' variable that controls the maximum size of its
communication buffer.  To set the `max_allowed_packet' variable for
`mysql' to a value of 16MB, use either of the following commands:

     shell> mysql --max_allowed_packet=16777216
     shell> mysql --max_allowed_packet=16M

The first command specifies the value in bytes. The second specifies
the value in megabytes. Variable values can have a suffix of `K', `M',
or `G' (either uppercase or lowercase) to indicate units of kilobytes,
megabytes, or gigabytes.

In an option file, the variable setting is given without the leading
dashes:

     [mysql]
     max_allowed_packet=16777216

Or:

     [mysql]
     max_allowed_packet=16M

If you like, underscores in a variable name can be specified as dashes.

Prior to MySQL 4.0.2, program variable names are not recognized as
option names.  Instead, use the `--set-variable' option to assign a
value to a variable:

     shell> mysql --set-variable=max_allowed_packet=16777216
     shell> mysql --set-variable=max_allowed_packet=16M

In an option file, omit the leading dashes:

     [mysql]
     set-variable = max_allowed_packet=16777216

Or:

     [mysql]
     set-variable = max_allowed_packet=16M

With `--set-variable', underscores in variable names cannot be given as
dashes for versions of MySQL older than 4.0.2.

The `--set-variable' option is still recognized in MySQL 4.0.2 and up,
but is deprecated.

Some server variables can be set at runtime. For details, see *Note
Dynamic System Variables::.

Database Administration
***********************

This chapter covers topics that deal with administering a MySQL
installation, such as configuring the server, managing user accounts,
and performing backups.

The MySQL Server and Server Startup Scripts
===========================================

The MySQL server, `mysqld', is the main program that does most of the
work in a MySQL installation. The server is accompanied by several
related scripts that perform setup operations when you install MySQL or
that are helper programs to assist you in starting and stopping the
server.

This section provides an overview of the server and related programs,
and information about server startup scripts. Information about
configuring the server itself is given in *Note Configuring MySQL::.

Overview of the Server-Side Scripts and Utilities
-------------------------------------------------

All MySQL programs take many different options. However, every MySQL
program provides a `--help' option that you can use to get a
description of the program's options. For example, try `mysqld --help'.

You can override default options for all standard programs by specifying
options on the command line or in an option file.  *Note Program
Options::.

The following list briefly describes the MySQL server and server-related
programs:

`mysqld'
     The SQL daemon (that is, the MySQL server). To use client
     programs, this program must be running, because clients gain
     access to databases by connecting to the server.  *Note
     Configuring MySQL::.

`mysqld-max'
     A version of the server that includes additional features.  *Note
     `mysqld-max': mysqld-max.

`mysqld_safe'
     A server startup script.  `mysqld_safe' attempts to start
     `mysqld-max' if it exists, and `mysqld' otherwise.  *Note
     `mysqld_safe': mysqld_safe.

`mysql.server'
     A server startup script.  This script is used on systems that use
     run directories containing scripts that start system services for
     particular run levels. It invokes `mysqld_safe' to start the MySQL
     server.  *Note `mysql.server': mysql.server.

`mysqld_multi'
     A server startup script that can start or stop multiple servers
     installed on the system.  *Note `mysqld_multi': mysqld_multi.

`mysql_install_db'
     This script creates the MySQL grant tables with default
     privileges. It is usually executed only once, when first
     installing MySQL on a system.

`mysql_fix_privilege_tables'
     This script is used after an upgrade install operation, to update
     the grant tables with any changes that have been made in newer
     versions of MySQL.

There are several other programs that also are run on the server host:

`myisamchk'
     A utility to describe, check, optimize, and repair `MyISAM' tables.
     `myisamchk' is described in *Note Table maintenance::.

`make_binary_distribution'
     This program makes a binary release of a compiled MySQL. This
     could be sent by FTP to `/pub/mysql/upload/' on `ftp.mysql.com'
     for the convenience of other MySQL users.

`mysqlbug'
     The MySQL bug reporting script.  It can be used to send a bug
     report to the MySQL mailing list. (You can also visit
     `http://bugs.mysql.com/' to file a bug report online.)

The `mysqld-max' Extended MySQL Server
--------------------------------------

A MySQL-Max server is a version of the `mysqld' MySQL server that has
been built to include additional features.

The distribution to use depends on your platform:

   * For Windows, MySQL binary distributions include both the standard
     server (`mysqld.exe') and the MySQL-Max server (`mysqld-max.exe'),
     so you need not get a special distribution. Just use a regular
     Windows distribution, available at
     `http://dev.mysql.com/downloads/mysql-4.0.html'.  *Note Windows
     installation::.

   * For Linux, if you install MySQL using RPM distributions, use the
     regular `MySQL-server' RPM first to install a standard server named
     `mysqld'.  Then use the `MySQL-Max' RPM to install a server named
     `mysqld-max'.  The `MySQL-Max' RPM presupposes that you have
     already installed the regular server RPM.  See *Note Linux-RPM::
     for more information on the Linux RPM packages.

   * All other MySQL-Max distributions contain a single server that is
     named `mysqld' but that has the additional features included.


You can find the MySQL-Max binaries on the MySQL AB Web site at
`http://dev.mysql.com/downloads/mysql-4.0.html'.

MySQL AB builds the MySQL-Max servers by using the following
`configure' options:

`--with-server-suffix=-max'
     This option adds a `-max' suffix to the `mysqld' version string.

`--with-innodb'
     This option enables support for the `InnoDB' storage engine.
     MySQL-Max servers always include `InnoDB' support, but this option
     actually is needed only for MySQL 3.23.  From MySQL 4 on, `InnoDB'
     is included by default in binary distributions, so you do not need
     a MySQL-Max server to obtain `InnoDB' support.

`--with-bdb'
     This option enables support for the Berkeley DB (`BDB') storage
     engine.

`CFLAGS=-DUSE_SYMDIR'
     This define enables symbolic link support for Windows.

MySQL-Max binary distributions are a convenience for those who wish to
install precompiled programs. If you build MySQL using a source
distribution, you can build your own Max-like server by enabling the
same features at configuration time that the MySQL-Max binary
distributions are built with.

MySQL-Max servers include the BerkeleyDB (`BDB') storage engine
whenever possible, but not all platforms support `BDB'.  The following
table shows which platforms allow MySQL-Max binaries to include `BDB':

*System*       `BDB'
               *Support*
AIX 4.3        N
HP-UX 11.0     N
Linux-Alpha    N
Linux-IA-64    N
Linux-Intel    Y
Mac OS X       N
NetWare        N
SCO OSR5       Y
Solaris-Intel  N
Solaris-SPARC  Y
UnixWare       Y
Windows/NT     Y

To find out which storage engines your server supports, issue the
following statement:

     mysql> SHOW ENGINES;

Before MySQL 4.1.2, `SHOW ENGINES' is unavailable. Use the following
statement instead and check the value of the variable for the storage
engine in which you are interested:

     mysql> SHOW VARIABLES LIKE 'have_%';
     +------------------+----------+
     | Variable_name    | Value    |
     +------------------+----------+
     | have_bdb         | NO       |
     | have_crypt       | YES      |
     | have_innodb      | YES      |
     | have_isam        | NO       |
     | have_raid        | NO       |
     | have_symlink     | DISABLED |
     | have_openssl     | NO       |
     | have_query_cache | YES      |
     +------------------+----------+

The values in the second column indicate the server's level of support
for each feature:

*Value*     *Meaning*
`YES'       The feature is supported and is active.
`NO'        The feature is not supported.
`DISABLED'  The feature is supported but has been disabled.

A value of `NO' means that the server was compiled without support for
the feature, so it cannot be activated at runtime.

A value of `DISABLED' occurs either because the server was started with
an option that disables the feature, or because not all options
required to enable it were given. In the latter case, the
`HOST_NAME.err' error log file should contain a reason indicating why
the option is disabled.

One situation in which you might see `DISABLED' occurs with MySQL 3.23
when the `InnoDB' storage engine is compiled in. In MySQL 3.23, you
must supply at least the `innodb_data_file_path' option at runtime to
set up the `InnoDB' tablespace. Without this option, `InnoDB' disables
itself.  *Note `InnoDB' in MySQL 3.23: InnoDB in MySQL 3.23.  You can
specify configuration options for the `BDB' storage engine, too, but
`BDB' will not disable itself if you do not provide them.  *Note `BDB'
start: BDB start.

You might also see `DISABLED' for the `InnoDB', `BDB', or `ISAM'
storage engines if the server was compiled to support them, but was
started with the `--skip-innodb', `--skip-bdb', or `--skip-isam'
options at runtime.

As of Version 3.23, all MySQL servers support `MyISAM' tables, because
`MyISAM' is the default storage engine.

The `mysqld_safe' Server Startup Script
---------------------------------------

`mysqld_safe' is the recommended way to start a `mysqld' server on Unix
and NetWare.  `mysqld_safe' adds some safety features such as
restarting the server when an error occurs and logging runtime
information to an error log file. NetWare-specific behaviors are listed
later in this section.

*Note*: Before MySQL 4.0, `mysqld_safe' is named `safe_mysqld'.  To
preserve backward compatibility, MySQL binary distributions for some
time will include `safe_mysqld' as a symbolic link to `mysqld_safe'.

By default, `mysqld_safe' tries to start an executable named
`mysqld-max' if it exists, or `mysqld' otherwise.  Be aware of the
implications of this behavior:

   * On Linux, the `MySQL-Max' RPM relies on this `mysqld_safe'
     behavior. The RPM installs an executable named `mysqld-max', which
     causes `mysqld_safe' to automatically use that executable from that
     point on.

   * If you install a MySQL-Max distribution that includes a server
     named `mysqld-max', then upgrade later to a non-Max version of
     MySQL, `mysqld_safe' will still attempt to run the old `mysqld-max'
     server.  If you perform such an upgrade, you should manually
     remove the old `mysqld-max' server to ensure that `mysqld_safe'
     runs the new `mysqld' server.


To override the default behavior and specify explicitly which server you
want to run, specify a `--mysqld' or `--mysqld-version' option to
`mysqld_safe'.

Many of the options to `mysqld_safe' are the same as the options to
`mysqld'. *Note Server options::.

All options specified to `mysqld_safe' on the command line are passed
to `mysqld'.  If you want to use any options that are specific to
`mysqld_safe' and that `mysqld' doesn't support, do not specify them on
the command line. Instead, list them in the `[mysqld_safe]' group of an
option file.  *Note Option files::.

`mysqld_safe' reads all options from the `[mysqld]', `[server]', and
`[mysqld_safe]' sections in option files.  For backward compatibility,
it also reads `[safe_mysqld]' sections, although you should rename such
sections to `[mysqld_safe]' when you begin using MySQL 4.0 or later.

`mysqld_safe' supports the following options:

`--basedir=PATH'
     The path to the MySQL installation directory.

`--core-file-size=SIZE'
     The size of the core file `mysqld' should be able to create. The
     option value is passed to `ulimit -c'.

`--datadir=PATH'
     The path to the data directory.

`--defaults-extra-file=PATH'
     The name of an option file to be read in addition to the usual
     option files.

`--defaults-file=PATH'
     The name of an option file to be read instead of the usual option
     files.

`--err-log=PATH'
     The old form of the `--log-error' option, to be used before MySQL
     4.0.

`--ledir=PATH'
     The path to the directory containing the `mysqld' program.  Use
     this option to explicitly indicate the location of the server.

`--log-error=PATH'
     Write the error log to the given file. *Note Error log::.

`--mysqld=PROG_NAME'
     The name of the server program (in the `ledir' directory) that you
     want to start. This option is needed if you use the MySQL binary
     distribution but have the data directory outside of the binary
     distribution.

`--mysqld-version=SUFFIX'
     This option is similar to the `--mysqld' option, but you specify
     only the suffix for the server program name. The basename is
     assumed to be `mysqld'.  For example, if you use
     `--mysqld-version=max', `mysqld_safe' will start the `mysqld-max'
     program in the `ledir' directory.  If the argument to
     `--mysqld-version' is empty, `mysqld_safe' uses `mysqld' in the
     `ledir' directory.

`--nice=PRIORITY'
     Use the `nice' program to set the server's scheduling priority to
     the given value.  This option was added in MySQL 4.0.14.

`--no-defaults'
     Do not read any option files.

`--open-files-limit=COUNT'
     The number of files `mysqld' should be able to open. The option
     value is passed to `ulimit -n'. Note that you need to start
     `mysqld_safe' as `root' for this to work properly!

`--pid-file=PATH'
     The path to the process ID file.

`--port=PORT_NUM'
     The port number to use when listening for TCP/IP connections.

`--socket=PATH'
     The Unix socket file to use for local connections.

`--timezone=ZONE'
     Set the `TZ' time zone environment variable to the given option
     value.  Consult your operating system documentation for legal time
     zone specification formats.

`--user={USER_NAME | USER_ID}'
     Run the `mysqld' server as the user having the name USER_NAME or
     the numeric user ID USER_ID.  ("User" in this context refers to a
     system login account, not a MySQL user listed in the grant tables.)

The `mysqld_safe' script is written so that it normally can start a
server that was installed from either a source or a binary distribution
of MySQL, even though these types of distributions typically install
the server in slightly different locations.  (*Note Installation
layouts::.)  `mysqld_safe' expects one of the following conditions to
be true:

   * The server and databases can be found relative to the directory
     from which `mysqld_safe' is invoked.  For binary distributions,
     `mysqld_safe' looks under its working directory for `bin' and
     `data' directories.  For source distributions, it looks for
     `libexec' and `var' directories.  This condition should be met if
     you execute `mysqld_safe' from your MySQL installation directory
     (for example, `/usr/local/mysql' for a binary distribution).

   * If the server and databases cannot be found relative to the working
     directory, `mysqld_safe' attempts to locate them by absolute
     pathnames.  Typical locations are `/usr/local/libexec' and
     `/usr/local/var'.  The actual locations are determined from the
     values configured into the distribution at the time it was built.
     They should be correct if MySQL is installed in the location
     specified at configuration time.

Because `mysqld_safe' will try to find the server and databases relative
to its own working directory, you can install a binary distribution of
MySQL anywhere, as long as you run `mysqld_safe' from the MySQL
installation directory:

     shell> cd mysql_installation_directory
     shell> bin/mysqld_safe &

If `mysqld_safe' fails, even when invoked from the MySQL installation
directory, you can specify the `--ledir' and `--datadir' options to
indicate the directories in which the server and databases are located
on your system.

Normally, you should not edit the `mysqld_safe' script.  Instead,
configure `mysqld_safe' by using command-line options or options in the
`[mysqld_safe]' section of a `my.cnf' option file.  In rare cases, it
might be necessary to edit `mysqld_safe' to get it to start the server
properly. However, if you do this, your modified version of
`mysqld_safe' might be overwritten if you upgrade MySQL in the future,
so you should make a copy of your edited version that you can reinstall.

On NetWare, `mysqld_safe' is a NetWare Loadable Module (NLM) that is
ported from the original Unix shell script.  It does the following:

  1. Runs a number of system and option checks.

  2. Runs a check on `MyISAM' and `ISAM' tables.

  3. Provides a screen presence for the MySQL server.

  4. Starts `mysqld', monitors it, and restarts it if it terminates in
     error.

  5. Sends error messages from `mysqld' to the `HOST_NAME.err' file in
     the data directory.

  6. Sends `mysqld_safe' screen output to the `HOST_NAME.safe' file in
     the data directory.


The `mysql.server' Server Startup Script
----------------------------------------

MySQL distributions on Unix include a script named `mysql.server'.  It
can be used on systems such as Linux and Solaris that use System V-style
run directories to start and stop system services. It is also used by
the Mac OS X Startup Item for MySQL.

`mysql.server' can be found in the `support-files' directory under your
MySQL installation directory or in a MySQL source tree.

If you use the Linux server RPM package (`MySQL-server-VERSION.rpm'),
the `mysql.server' script will already have been installed in the
`/etc/init.d' directory with the name `mysql'. You need not install it
manually. See *Note Linux-RPM:: for more information on the Linux RPM
packages.

Some vendors provide RPM packages that install a startup script under a
different name such as `mysqld'.

If you install MySQL from a source distribution or using a binary
distribution format that does not install `mysql.server' automatically,
you can install it manually. Instructions are provided in *Note
Automatic start::.

`mysql.server' reads options from the `[mysql.server]' and `[mysqld]'
sections of option files.  (For backward compatibility, it also reads
`[mysql_server]' sections, although you should rename such sections to
`[mysql.server]' when you begin using MySQL 4.0 or later.)

The `mysqld_multi' Program for Managing Multiple MySQL Servers
--------------------------------------------------------------

`mysqld_multi' is meant for managing several `mysqld' processes that
listen for connections on different Unix socket files and TCP/IP ports.
It can start or stop servers, or report their current status.

The program searches for groups named `[mysqld#]' in `my.cnf' (or in
the file named by the `--config-file' option).  `#' can be any positive
integer.  This number is referred to in the following discussion as the
option group number, or GNR.  Group numbers distinguish option groups
from one another and are used as arguments to `mysqld_multi' to specify
which servers you want to start, stop, or obtain a status report for.
Options listed in these groups are the same that you would use in the
`[mysqld]' group used for starting `mysqld'.  (See, for example, *Note
Automatic start::.) However, when using multiple servers it is necessary
that each one use its own value for options such as the Unix socket
file and TCP/IP port number. For more information on which options must
be unique per server in a multiple-server environment, see *Note
Multiple servers::.

To invoke `mysqld_multi', use the following syntax:

     shell> mysqld_multi [OPTIONS] {start|stop|report} [GNR[,GNR]...]

`start', `stop', and `report' indicate which operation you want to
perform. You can perform the designated operation on a single server or
multiple servers, depending on the GNR list that follows the option
name.  If there is no list, `mysqld_multi' performs the operation for
all servers in the option file.

Each GNR value represents an option group number or range of group
numbers.  The value should be the number at the end of the group name
in the option file.  For example, the GNR for a group named `[mysqld17]'
is `17'.  To specify a range of numbers, separate the first and last
numbers by a dash.  The GNR value `10-13' represents groups
`[mysqld10]' through `[mysqld13]'.  Multiple groups or group ranges can
be specified on the command line, separated by commas.  There must be
no whitespace characters (spaces or tabs) in the GNR list; anything
after a whitespace character is ignored.

This command starts a single server using option group `[mysqld17]':

     shell> mysqld_multi start 17

This command stops several servers, using option groups `[mysql8]' and
`[mysqld10]' through `[mysqld13]':

     shell> mysqld_multi stop 8,10-13

For an example of how you might set up an option file, use this command:

     shell> mysqld_multi --example

`mysqld_multi' supports the following options:

`--config-file=NAME'
     Specify the name of an alternative option file. This affects where
     `mysqld_multi' looks for `[mysqld#]' option groups.  Without this
     option, all options are read from the usual `my.cnf' file.  The
     option does not affect where `mysqld_multi' reads its own options,
     which are always taken from the `[mysqld_multi]' group in the
     usual `my.cnf' file.

`--example'
     Display a sample option file.

`--help'
     Display a help message and exit.

`--log=NAME'
     Specify the name of the log file. If the file exists, log output
     is appended to it.

`--mysqladmin=PROG_NAME'
     The `mysqladmin' binary to be used to stop servers.

`--mysqld=PROG_NAME'
     The `mysqld' binary to be used. Note that you can specify
     `mysqld_safe' as the value for this option also. The options are
     passed to `mysqld'. Just make sure that you have the directory
     where `mysqld' is located in your `PATH' environment variable
     setting or fix `mysqld_safe'.

`--no-log'
     Print log information to stdout rather than to the log file. By
     default, output goes to the log file.

`--password=PASSWORD'
     The password of the MySQL account to use when invoking
     `mysqladmin'.  Note that the password value is not optional for
     this option, unlike for other MySQL programs.

`--silent'
     Disable warnings.  This option was added in MySQL 4.1.6.

`--tcp-ip'
     Connect to each MySQL server via the TCP/IP port instead of the
     Unix socket file.  (If a socket file is missing, the server might
     still be running, but accessible only via the TCP/IP port.)  By
     default, connections are made using the Unix socket file.  This
     option affects `stop' and `report' operations.

`--user=USER_NAME'
     The username of the MySQL account to use when invoking
     `mysqladmin'.

`--verbose'
     Be more verbose.  This option was added in MySQL 4.1.6.

`--version'
     Display version information and exit.

Some notes about `mysqld_multi':

   * Make sure that the MySQL account used for stopping the `mysqld'
     servers (with the `mysqladmin' program) has the same username and
     password for each server. Also, make sure that the account has the
     `SHUTDOWN' privilege. If the servers that you want to manage have
     many different usernames or passwords for the administrative
     accounts, you might want to create an account on each server that
     has the same username and password.  For example, you might set up
     a common `multi_admin' account by executing the following commands
     for each server:

          shell> mysql -u root -S /tmp/mysql.sock -pROOT_PASSWORD
          mysql> GRANT SHUTDOWN ON *.*
              -> TO 'multi_admin'@'localhost' IDENTIFIED BY 'multipass';

     *Note Privileges::.  You will have to do this for each `mysqld'
     server. Change the connection parameters appropriately when
     connecting to each one.  Note that the host part of the account
     name must allow you to connect as `multi_admin' from the host
     where you want to run `mysqld_multi'.

   * The `--pid-file' option is very important if you are using
     `mysqld_safe' to start `mysqld' (for example,
     `--mysqld=mysqld_safe') Every `mysqld' should have its own process
     ID file. The advantage of using `mysqld_safe' instead of `mysqld'
     is that `mysqld_safe' "guards" its `mysqld' process and will
     restart it if the process terminates due to a signal sent using
     `kill -9', or for other reasons, such as a segmentation fault.
     Please note that the `mysqld_safe' script might require that you
     start it from a certain place. This means that you might have to
     change location to a certain directory before running
     `mysqld_multi'. If you have problems starting, please see the
     `mysqld_safe' script. Check especially the lines:

          ----------------------------------------------------------------
          MY_PWD=`pwd`
          # Check if we are starting this relative (for the binary release)
          if test -d $MY_PWD/data/mysql -a -f ./share/mysql/english/errmsg.sys -a \
           -x ./bin/mysqld
          ----------------------------------------------------------------

     *Note `mysqld_safe': mysqld_safe.  The test performed by these
     lines should be successful, or you might encounter problems.

   * The Unix socket file and the TCP/IP port number must be different
     for every `mysqld'.

   * You might want to use the `--user' option for `mysqld', but in
     order to do this you need to run the `mysqld_multi' script as the
     Unix `root' user. Having the option in the option file doesn't
     matter; you will just get a warning, if you are not the superuser
     and the `mysqld' processes are started under your own Unix account.

   * *Important*: Make sure that the data directory is fully accessible
     to the Unix account that the specific `mysqld' process is started
     as. _Do not_ use the Unix root account for this, unless you _know_
     what you are doing.

   * *Most important*: Before using `mysqld_multi' be sure that you
     understand the meanings of the options that are passed to the
     `mysqld' servers and _why_ you would want to have separate `mysqld'
     processes.  Beware of the dangers of using multiple `mysqld'
     servers with the same data directory.  Use separate data
     directories, unless you _know_ what you are doing.  Starting
     multiple servers with the same data directory _will not_ give you
     extra performance in a threaded system.  *Note Multiple servers::.


The following example shows how you might set up an option file for use
with `mysqld_multi'.  The first and fifth `[mysqld#]' group were
intentionally left out from the example to illustrate that you can have
"gaps" in the option file. This gives you more flexibility.  The order
in which the `mysqld' programs are started or stopped depends on the
order in which they appear in the option file.

     # This file should probably be in your home dir (~/.my.cnf)
     # or /etc/my.cnf
     # Version 2.1 by Jani Tolonen

     [mysqld_multi]
     mysqld     = /usr/local/bin/mysqld_safe
     mysqladmin = /usr/local/bin/mysqladmin
     user       = multi_admin
     password   = multipass

     [mysqld2]
     socket     = /tmp/mysql.sock2
     port       = 3307
     pid-file   = /usr/local/mysql/var2/hostname.pid2
     datadir    = /usr/local/mysql/var2
     language   = /usr/local/share/mysql/english
     user       = john

     [mysqld3]
     socket     = /tmp/mysql.sock3
     port       = 3308
     pid-file   = /usr/local/mysql/var3/hostname.pid3
     datadir    = /usr/local/mysql/var3
     language   = /usr/local/share/mysql/swedish
     user       = monty

     [mysqld4]
     socket     = /tmp/mysql.sock4
     port       = 3309
     pid-file   = /usr/local/mysql/var4/hostname.pid4
     datadir    = /usr/local/mysql/var4
     language   = /usr/local/share/mysql/estonia
     user       = tonu

     [mysqld6]
     socket     = /tmp/mysql.sock6
     port       = 3311
     pid-file   = /usr/local/mysql/var6/hostname.pid6
     datadir    = /usr/local/mysql/var6
     language   = /usr/local/share/mysql/japanese
     user       = jani

*Note Option files::.

Configuring the MySQL Server
============================

This section discusses MySQL server configuration topics:

   * Startup options that the server supports

   * How to set the server SQL mode

   * Server system variables

   * Server status variables

`mysqld' Command-Line Options
-----------------------------

When you start the `mysqld' server, you can specify program options
using any of the methods described in *Note Program Options::. The most
common methods are to provide options in an option file or on the
command line. However, in most cases it is desirable to make sure that
the server uses the same options each time it runs. The best way to
ensure this is to list them in an option file.  *Note Option files::.

`mysqld' reads options from the `[mysqld]' and `[server]' groups.
`mysqld_safe' reads options from the `[mysqld]', `[server]',
`[mysqld_safe]', and `[safe_mysqld]' groups.  `mysql.server' reads
options from the `[mysqld]' and `[mysql.server]' groups.  An embedded
MySQL server usually reads options from the `[server]', `[embedded]',
and `[XXXXX_SERVER]' groups, where XXXXX is the name of the application
into which the server is embedded.

`mysqld' accepts many command-line options.  For a list, execute
`mysqld --help'. Before MySQL 4.1.1, `--help' prints the full help
message. As of 4.1.1, it prints a brief message; to see the full list,
use `mysqld --verbose --help'.

The following list shows some of the most common server options.
Additional options are described elsewhere:

   * Options that affect security: See *Note Privileges options::.

   * SSL-related options: See *Note SSL options::.

   * Binary log control options: See *Note Binary log::.

   * Replication-related options: See *Note Replication Options::.

   * Options specific to particular storage engines: See *Note `MyISAM'
     start: MyISAM start, *Note `BDB' start: BDB start, *Note `InnoDB'
     start: InnoDB start.


You can also set the value of a server system variable by using the
variable name as an option, as described later in this section.

`--help, -?'
     Display a short help message and exit.  Before MySQL 4.1.1,
     `--help' displays the full help message.  As of 4.1.1, it displays
     an abbreviated message only.  Use both the `--verbose' and
     `--help' options to see the full message.

`--ansi'
     Use standard SQL syntax instead of MySQL syntax.  *Note ANSI
     mode::.  For more precise control over the server SQL mode, use
     the `--sql-mode' option instead.

`--basedir=PATH, -b PATH'
     The path to the MySQL installation directory. All paths are
     usually resolved relative to this.

`--big-tables'
     Allow large result sets by saving all temporary sets in files.
     This option prevents most "table full" errors, but also slows down
     queries for which in-memory tables would suffice.  Since MySQL
     3.23.2, the server is able to handle large result sets
     automatically by using memory for small temporary tables and
     switching to disk tables where necessary.

`--bind-address=IP'
     The IP address to bind to.

`--console'
     Write the error log messages to stderr/stdout even if `--log-error'
     is specified.  On Windows, `mysqld' will not close the console
     screen if this option is used.

`--character-sets-dir=PATH'
     The directory where character sets are installed.  *Note Character
     sets::.

`--chroot=PATH'
     Put the `mysqld' server in a closed environment during startup by
     using the `chroot()' system call. This is a recommended security
     measure as of MySQL 4.0. (MySQL 3.23 is not able to provide a
     `chroot()' jail that is 100% closed.)  Note that use of this
     option somewhat limits `LOAD DATA INFILE' and `SELECT ... INTO
     OUTFILE'.

`--character-set-server=CHARSET'
     Use CHARSET as the default server character set.  This option is
     available as of MySQL 4.1.3.  *Note Character sets::.

`--core-file'
     Write a core file if `mysqld' dies.  For some systems, you must
     also specify the `--core-file-size' option to `mysqld_safe'.
     *Note `mysqld_safe': mysqld_safe.  Note that on some systems, such
     as Solaris, you will not get a core file if you are also using the
     `--user' option.

`--collation-server=COLLATION'
     Use COLLATION as the default server collation.  This option is
     available as of MySQL 4.1.3.  *Note Character sets::.

`--datadir=PATH, -h PATH'
     The path to the data directory.

`--debug[=DEBUG_OPTIONS], -# [DEBUG_OPTIONS]'
     If MySQL is configured with `--with-debug', you can use this
     option to get a trace file of what `mysqld' is doing.  The
     DEBUG_OPTIONS string often is `'d:t:o,FILE_NAME''.  *Note Making
     trace files::.

`--default-character-set=CHARSET'
     Use CHARSET as the default character set.  This option is
     deprecated in favor of `--character-set-server' as of MySQL 4.1.3.
     *Note Character sets::.

`--default-collation=COLLATION'
     Use COLLATION as the default collation.  This option is deprecated
     in favor of `--collation-server' as of MySQL 4.1.3.  *Note
     Character sets::.

`--default-storage-engine=TYPE'
     This option is a synonym for `--default-table-type'.  It is
     available as of MySQL 4.1.2.

`--default-table-type=TYPE'
     Set the default table type for tables.  *Note Storage engines::.

`--default-time-zone=TYPE'
     Set the default server time zone.  This option sets the global
     `time_zone' system variable.  If this option is not given, the
     default time zone will be the same as the system time zone (given
     by the value of the `system_time_zone' system variable.  This
     option is available as of MySQL 4.1.3.

`--delay-key-write[= OFF | ON | ALL]'
     How the `DELAYED KEYS' option should be used.  Delayed key writing
     causes key buffers not to be flushed between writes for `MyISAM'
     tables.  `OFF' disables delayed key writes.  `ON' enables delayed
     key writes for those tables that were created with the `DELAYED
     KEYS' option.  `ALL' delays key writes for all `MyISAM' tables.
     Available as of MySQL 4.0.3.  *Note Server parameters::. *Note
     MyISAM start::.

     *Note*: If you set this variable to `ALL', you should not use
     `MyISAM' tables from within another program (such as from another
     MySQL server or with `myisamchk') when the table is in use. Doing
     so will lead to index corruption.

`--delay-key-write-for-all-tables'
     Old form of `--delay-key-write=ALL' for use prior to MySQL 4.0.3.
     As of 4.0.3, use `--delay-key-write' instead.

`--des-key-file=FILE_NAME'
     Read the default keys used by `DES_ENCRYPT()' and `DES_DECRYPT()'
     from this file.

`--enable-named-pipe'
     Enable support for named pipes.  This option applies only on
     Windows NT, 2000, and XP systems, and can be used only with the
     `mysqld-nt' and `mysqld-max-nt' servers that support named pipe
     connections.

`--exit-info[=FLAGS], -T [FLAGS]'
     This is a bit mask of different flags you can use for debugging the
     `mysqld' server. Do not use this option unless you know exactly
     what it does!

`--external-locking'
     Enable system locking.  Note that if you use this option on a
     system on which `lockd' does not fully work (as on Linux), you
     will easily get `mysqld' to deadlock.  This option previously was
     named `--enable-locking'.

     *Note*: If you use this option to enable updates to `MyISAM'
     tables from many MySQL processes, you have to ensure that these
     conditions are satisfied:

        * You should not use the query cache for queries that use
          tables that are updated by another process.

        * You should not use `--delay-key-write=ALL' or
          `DELAY_KEY_WRITE=1' on any shared tables.

     The easiest way to ensure this is to always use
     `--external-locking' together with `--delay-key-write=OFF
     --query-cache-size=0'.

     (This is not done by default because in many setups it's useful to
     have a mixture of the above options.)

`--flush'
     Flush all changes to disk after each SQL statement.  Normally MySQL
     does a write of all changes to disk only after each SQL statement
     and lets the operating system handle the synching to disk.  *Note
     Crashing::.

`--init-file=FILE'
     Read SQL statements from this file at startup.  Each statement
     must be on a single line and should not include comments.

`--innodb-safe-binlog'
     Adds consistency guarantees between the content of `InnoDB' tables
     and the binary log.  *Note Binary log::.

`--language=LANG_NAME, -L LANG_NAME'
     Client error messages in given language.  LANG_NAME can be given
     as the language name or as the full pathname to the directory
     where the language files are installed.  *Note Languages::.

`--log[=FILE], -l [FILE]'
     Log connections and queries to this file. *Note Query log::. If
     you don't specify a filename, MySQL will use `HOST_NAME.log' as
     the filename.

`--log-bin=[FILE]'
     The binary log file.  Log all queries that change data to this
     file. Used for backup and replication.  *Note Binary log::.  If
     you don't specify a filename, MySQL will use `HOST_NAME-bin' as
     the filename.

`--log-bin-index[=FILE]'
     The index file for binary log filenames. *Note Binary log::.  If
     you don't specify a filename, MySQL will use `HOST_NAME-bin.index'
     as the filename.

`--log-error[=FILE]'
     Log errors and startup messages to this file. *Note Error log::.
     If you don't specify a filename, MySQL will use `HOST_NAME.err' as
     the filename.

`--log-isam[=FILE]'
     Log all `ISAM'/`MyISAM' changes to this file (used only when
     debugging `ISAM'/`MyISAM').

`--log-long-format'
     Log some extra information to the log files (update log, binary
     update log, and slow queries log, whatever log has been
     activated). For example, username and timestamp are logged for
     queries. If you are using `--log-slow-queries' and
     `--log-long-format', queries that are not using indexes also are
     logged to the slow query log.  Note that `--log-long-format' is
     deprecated as of MySQL version 4.1, when `--log-short-format' was
     introduced (the long log format is the default setting since
     version 4.1). Also note that starting with MySQL 4.1, the
     `--log-queries-not-using-indexes' option is available for the
     purpose of logging queries that do not use indexes to the slow
     query log.

`--log-queries-not-using-indexes'
     If you are using this option with `--log-slow-queries', then
     queries that are not using indexes also  are logged to the slow
     query log. This option is available as of MySQL 4.1. *Note Slow
     query log::.

`--log-short-format'
     Log less information to the log files (update log, binary update
     log, and slow queries log, whatever log has been activated). For
     example, username and timestamp are not logged for queries. This
     option was introduced in MySQL 4.1.

`--log-slow-queries[=FILE]'
     Log all queries that have taken more than `long_query_time' seconds
     to execute to this file.  *Note Slow query log::.  Note that the
     default for the amount of information logged has changed in MySQL
     4.1. See the `--log-long-format' and `--log-short-format' options
     for details.

`--log-update[=FILE]'
     Log updates to FILE# where # is a unique number if not given.
     *Note Update log::. The update log is deprecated and is removed in
     MySQL 5.0.0; you should use the binary log instead (`--log-bin').
     *Note Binary log::. Starting from version 5.0.0, using
     `--log-update' will just turn on the binary log instead (*note
     News-5.0.0::).

`--log-warnings, -W'
     Print out warnings such as `Aborted connection...' to the error
     log.  Enabling this option is recommended, for example, if you use
     replication (you will get more information about what is happening,
     such as messages about network failures and reconnections).  This
     option is enabled by default as of MySQL 4.0.19 and 4.1.2; to
     disable it, use `--skip-log-warnings'.  As of MySQL 4.0.21 and
     4.1.3, aborted connections are not logged to the error log unless
     the value is greater than 1.  *Note Communication errors::.

     This option was named `--warnings' before MySQL 4.0.

`--low-priority-updates'
     Table-modifying operations (`INSERT', `REPLACE', `DELETE',
     `UPDATE') will have lower priority than selects.  This can also be
     done via `{INSERT | REPLACE | DELETE | UPDATE} LOW_PRIORITY ...'
     to lower the priority of only one query, or by `SET
     LOW_PRIORITY_UPDATES=1' to change the priority in one thread.
     *Note Table locking::.

`--memlock'
     Lock the `mysqld' process in memory.  This works on systems such as
     Solaris that support the `mlockall()' system call.  This might
     help if you have a problem where the operating system is causing
     `mysqld' to swap on disk.  Note that use of this option requires
     that you run the server as `root', which is normally not a good
     idea for security reasons.

`--myisam-recover [=OPTION[,OPTION...]]]'
     Set the `MyISAM' storage engine recovery mode.  The option value
     is any combination of the values of `DEFAULT', `BACKUP', `FORCE',
     or `QUICK'.  If you specify multiple values, separate them by
     commas.  You can also use a value of `""' to disable this option.
     If this option is used, `mysqld' will, when it opens a `MyISAM'
     table, open check whether the table is marked as crashed or wasn't
     closed properly.  (The last option works only if you are running
     with `--skip-external-locking'.)  If this is the case, `mysqld'
     will run a check on the table. If the table was corrupted,
     `mysqld' will attempt to repair it.

     The following options affect how the repair works:

     *Option*   *Description*
     `DEFAULT'  The same as not giving any option to
                         `--myisam-recover'.
     `BACKUP'   If the data file was changed during recovery,
                save a                     backup of the
                `TBL_NAME.MYD' file as
                `TBL_NAME-DATETIME.BAK'.
     `FORCE'    Run recovery even if we will lose more than
                one row                     from the `.MYD'
                file.
     `QUICK'    Don't check the rows in the table if there
                aren't any                     delete blocks.

     Before a table is automatically repaired, MySQL will add a note
     about this in the error log.  If you want to be able to recover
     from most problems without user intervention, you should use the
     options `BACKUP,FORCE'.  This will force a repair of a table even
     if some rows would be deleted, but it will keep the old data file
     as a backup so that you can later examine what happened.

     This option is available as of MySQL 3.23.25.

`--ndb-connectstring=CONNECT_STRING'
     When using the `NDB' storage engine, it is possible to point out
     the management server that distributes the cluster configuration
     by setting the connect string option.

`--ndbcluster'
     If the binary includes support for the `NDB Cluster' storage engine
     (from version 4.1.3, the MySQL-Max binaries are built with `NDB
     Cluster' enabled) the default disabling of support for the `NDB
     Cluster' storage engine can be overruled by using this option.
     Using the `NDB Cluster' storage engine is necessary for using
     MySQL Cluster.  *Note NDBCluster::.

`--new'
     The `--new' option can be used to make the server behave as 4.1 in
     certain respects, easing a 4.0 to 4.1 upgrade:
        * Hexadecimal strings such as `0xFF' are treated as strings by
          default rather than as numbers.  (Works in 4.0.12 and up.)

        * `TIMESTAMP' is returned as a string with the format
          `'YYYY-MM-DD HH:MM:SS''.  (Works in 4.0.13 and up.)  *Note
          Column types::.

     This option can be used to help you see how your applications will
     behave in MySQL 4.1, without actually upgrading to 4.1.

`--pid-file=PATH'
     The path to the process ID file used by `mysqld_safe'.

`--port=PORT_NUM, -P PORT_NUM'
     The port number to use when listening for TCP/IP connections.

`--old-protocol, -o'
     Use the 3.20 protocol for compatibility with some very old clients.
     *Note Upgrading-from-3.20::.

`--one-thread'
     Only use one thread (for debugging under Linux).  This option is
     available only if the server is built with debugging enabled.
     *Note Debugging server::.

`--open-files-limit=COUNT'
     To change the number of file descriptors available to `mysqld'.
     If this is not set or set to 0, then `mysqld' will use this value
     to reserve file descriptors to use with `setrlimit()'.  If this
     value is 0 then `mysqld' will reserve `max_connections*5' or
     `max_connections + table_cache*2' (whichever is larger) number of
     files.  You should try increasing this if `mysqld' gives you the
     error "Too many open files."

`--safe-mode'
     Skip some optimization stages.

`--safe-show-database'
     With this option, the `SHOW DATABASES' statement displays only the
     names of those databases for which the user has some kind of
     privilege.  As of MySQL 4.0.2, this option is deprecated and
     doesn't do anything (it is enabled by default), because there is
     now a `SHOW DATABASES' privilege that can be used to control
     access to database names on a per-account basis.  *Note Privileges
     provided::.

`--safe-user-create'
     If this is enabled, a user can't create new users with the `GRANT'
     statement, if the user doesn't have the `INSERT' privilege for the
     `mysql.user' table or any column in the table.

`--secure-auth'
     Disallow authentication for accounts that have old (pre-4.1)
     passwords.  This option is available as of MySQL 4.1.1.

`--shared-memory'
     Enable shared-memory connections by local clients. This option is
     available only on Windows. It was added in MySQL 4.1.0.

`--shared-memory-base-name=NAME'
     The name to use for shared-memory connections.  This option is
     available only on Windows. It was added in MySQL 4.1.0.

`--skip-bdb'
     Disable the `BDB' storage engine. This saves memory and might speed
     up some operations.  Do not use this option if you require `BDB'
     tables.

`--skip-concurrent-insert'
     Turn off the ability to select and insert at the same time on
     `MyISAM' tables. (This is to be used only if you think you have
     found a bug in this feature.)

`--skip-delay-key-write'
     Ignore the `DELAY_KEY_WRITE' option for all tables.  As of MySQL
     4.0.3, you should use `--delay-key-write=OFF' instead.  *Note
     Server parameters::.

`--skip-external-locking'
     Don't use system locking.  To use `isamchk' or `myisamchk', you
     must shut down the server.  *Note Stability::.  In MySQL 3.23, you
     can use `CHECK TABLE' and `REPAIR TABLE' to check and repair
     `MyISAM' tables.  This option previously was named
     `--skip-locking'.

`--skip-grant-tables'
     This option causes the server not to use the privilege system at
     all. This gives everyone _full access_ to all databases!  (You can
     tell a running server to start using the grant tables again by
     executing a `mysqladmin flush-privileges' or `mysqladmin reload'
     command, or by issuing a `FLUSH PRIVILEGES' statement.)

`--skip-host-cache'
     Do not use the internal hostname cache for faster name-to-IP
     resolution.  Instead, query the DNS server every time a client
     connects.  *Note DNS::.

`--skip-innodb'
     Disable the `InnoDB' storage engine.  This saves memory and disk
     space and might speed up some operations.  Do not use this option
     if you require `InnoDB' tables.

`--skip-isam'
     Disable the `ISAM' storage engine.  As of MySQL 4.1, `ISAM' is
     disabled by default, so this option applies only if the server was
     configured with support for `ISAM'.  This option was added in
     MySQL 4.1.1.

`--skip-name-resolve'
     Do not resolve hostnames when checking client connections. Use
     only IP numbers. If you use this option, all `Host' column values
     in the grant tables must be IP numbers or `localhost'.  *Note
     DNS::.

`--skip-ndbcluster'
     Disable the `NDB Cluster' storage engine. This is the default for
     binaries that were built with `NDB Cluster' storage engine
     support, this means that the system will only allocate memory and
     other resources for this storage engine if it is explicitly
     enabled.

`--skip-networking'
     Don't listen for TCP/IP connections at all.  All interaction with
     `mysqld' must be made via named pipes (on Windows) or Unix socket
     files (on Unix).  This option is highly recommended for systems
     where only local clients are allowed.  *Note DNS::.

`--skip-new'
     Don't use new, possibly wrong routines.

`--skip-symlink'
     This is the old form of `--skip-symbolic-links', for use before
     MySQL 4.0.13.

`--symbolic-links, --skip-symbolic-links'
     Enable or disable symbolic link support. This option has different
     effects on Windows and Unix:

        * On Windows, enabling symbolic links allows you to establish a
          symbolic link to a database directory by creating a
          `directory.sym' file that contains the path to the real
          directory.  *Note Windows symbolic links::.

        * On Unix, enabling symbolic links means that you can link a
          `MyISAM' index file or data file to another directory with
          the `INDEX DIRECTORY' or `DATA DIRECTORY' options of the
          `CREATE TABLE' statement.  If you delete or rename the table,
          the files that its symbolic links point to also are deleted or
          renamed. *Note `CREATE TABLE': CREATE TABLE.

     This option was added in MySQL 4.0.13.

`--skip-safemalloc'
     If MySQL is configured with `--with-debug=full', all MySQL programs
     check for memory overruns during each memory allocation and memory
     freeing operation.  This checking is very slow, so for the server
     you can avoid it when you don't need it by using the
     `--skip-safemalloc' option.

`--skip-show-database'
     With this option, the `SHOW DATABASES' statement is allowed only to
     users who have the `SHOW DATABASES' privilege, and the statement
     displays all database names.  Without this option, `SHOW
     DATABASES' is allowed to all users, but displays each database
     name only if the user has the `SHOW DATABASES' privilege or some
     privilege for the database.

`--skip-stack-trace'
     Don't write stack traces.  This option is useful when you are
     running `mysqld' under a debugger. On some systems, you also must
     use this option to get a core file. *Note Debugging server::.

`--skip-thread-priority'
     Disable using thread priorities for faster response time.

`--socket=PATH'
     On Unix, this option specifies the Unix socket file to use for
     local connections. The default value is `/tmp/mysql.sock'.  On
     Windows, the option specifies the pipe name to use for local
     connections that use a named pipe. The default value is `MySQL'.

`--sql-mode=VALUE[,VALUE[,VALUE...]]'
     Set the SQL mode for MySQL. *Note Server SQL mode::. This option
     was added in 3.23.41.

`--temp-pool'
     This option causes most temporary files created by the server to
     use a small set of names, rather than a unique name for each new
     file. This works around a problem in the Linux kernel dealing with
     creating many new files with different names. With the old
     behavior, Linux seems to "leak" memory, because it's being
     allocated to the directory entry cache rather than to the disk
     cache.

`--transaction-isolation=LEVEL'
     Sets the default transaction isolation level, which can be
     `READ-UNCOMMITTED', `READ-COMMITTED', `REPEATABLE-READ', or
     `SERIALIZABLE'.  *Note `SET TRANSACTION': SET TRANSACTION.

`--tmpdir=PATH, -t PATH'
     The path of the directory to use for creating temporary files. It
     might be useful if your default `/tmp' directory resides on a
     partition that is too small to hold temporary tables.  Starting
     from MySQL 4.1, this option accepts several paths that are used in
     round-robin fashion. Paths should be separated by colon characters
     (`:') on Unix and semicolon characters (`;') on Windows, NetWare,
     and OS/2.  If the MySQL server is acting as a replication slave,
     you should not set `--tmpdir' to point to a directory on a
     memory-based filesystem or to a directory that is cleared when the
     server host restarts.  A replication slave needs some of its
     temporary files to survive a machine restart so that it can
     replicate temporary tables or `LOAD DATA INFILE' operations. If
     files in the temporary file directory are lost when the server
     restarts, replication will fail.

`--user={USER_NAME | USER_ID}, -u {USER_NAME | USER_ID}'
     Run the `mysqld' server as the user having the name USER_NAME or
     the numeric user ID USER_ID.  ("User" in this context refers to a
     system login account, not a MySQL user listed in the grant tables.)

     This option is _mandatory_ when starting `mysqld' as `root'.  The
     server will change its user ID during its startup sequence,
     causing it to run as that particular user rather than as `root'.
     *Note Security guidelines::.

     Starting from MySQL 3.23.56 and 4.0.12: To avoid a possible
     security hole where a user adds a `--user=root' option to some
     `my.cnf' file (thus causing the server to run as `root'), `mysqld'
     uses only the first `--user' option specified and produces a
     warning if there are multiple `--user' options. Options in
     `/etc/my.cnf' and `datadir/my.cnf' are processed before
     command-line options, so it is recommended that you put a `--user'
     option in `/etc/my.cnf' and specify a value other than `root'. The
     option in `/etc/my.cnf' will be found before any other `--user'
     options, which ensures that the server runs as a user other than
     `root', and that a warning results if any other `--user' option is
     found.

`--version, -V'
     Display version information and exit.

As of MySQL 4.0, you can assign a value to a server system variable by
using an option of the form `--VAR_NAME=VALUE'. For example,
`--key_buffer_size=32M' sets the `key_buffer_size' variable to a value
of 32MB.

Note that when setting a variable to a value, MySQL might automatically
correct it to stay within a given range, or adjust the value to the
closest allowable value if only certain values are allowed.

It is also possible to set variables by using
`--set-variable=VAR_NAME=VALUE' or `-O VAR_NAME=VALUE' syntax. However,
this syntax is deprecated as of MySQL 4.0.

You can find a full description for all variables in *Note Server
system variables::.  The section on tuning server parameters includes
information on how to optimize them.  *Note Server parameters::.

You can change the values of most system variables for a running server
with the `SET' statement. *Note `SET OPTION': SET OPTION.

If you want to restrict the maximum value that a startup option can be
set to with `SET', you can define this by using the
`--maximum-VAR_NAME' command-line option.

The Server SQL Mode
-------------------

The MySQL server can operate in different SQL modes, and (as of MySQL
4.1) can apply these modes differentially for different clients. This
allows an application to tailor server operation to its own
requirements.

Modes define what SQL syntax MySQL should support and what kind of data
validation checks it should perform.  This makes it easier to use MySQL
in different environments and to use MySQL together with other database
servers.

You can set the default SQL mode by starting `mysqld' with the
`--sql-mode="MODES"' option.  The value also can be empty
(`--sql-mode=""') if you want to reset it.

Beginning with MySQL 4.1, you can also change the SQL mode after
startup time by setting the `sql_mode' variable with a `SET
[SESSION|GLOBAL] sql_mode='MODES'' statement.  Setting the `GLOBAL'
variable requires the `SUPER' privilege and affects the operation of
all clients that connect from that time on. Setting the `SESSION'
variable affects only the current client.  Any client can change its
session `sql_mode' value.

MODES is a list of different modes separated by comma (`,') characters.
You can retrieve the current mode by issuing a `SELECT @@sql_mode'
statement. The default value is empty (no modes set).

The most important `sql_mode' values are probably these:

`ANSI'
     Change syntax and behavior to be more conformant to standard SQL.
     (New in MySQL 4.1.1)

`STRICT_TRANS_TABLES'
     If a value could not be inserted as given into a transactional
     table, abort the statement.  For a non-transactional table, abort
     the statement if the value occurs in a single-row statement or the
     first row of a multiple-row statement. More detail is given later
     in this section.  (New in MySQL 5.0.2)

`TRADITIONAL'
     Make MySQL behave like a "traditional" SQL database system.  A
     simple description of this mode is "give an error instead of a
     warning" when inserting an incorrect value into a column.  *Note*:
     The `INSERT'/`UPDATE' will abort as soon as the error is noticed.
     This may not be what you want if you are using a non-transactional
     storage engine, because data changes made prior to the error will
     not be rolled back, resulting in a "partially-done" update.  (New
     in MySQL 5.0.2)

When this manual refers to "strict mode," it means a mode where at least
one of `STRICT_TRANS_TABLES' or `STRICT_ALL_TABLES' is enabled.

The following list describes all the supported modes:

`ALLOW_INVALID_DATES'
     Don't do full checking of dates in strict mode. Check only that
     the month is in the range from 1 to 12 and the day is in the range
     from 1 to 31. This is very convenient for Web applications where
     you obtain year, month, and day in three different fields and you
     want to store exactly what the user inserted (without date
     validation).  This mode applies to `DATE' and `DATETIME' columns.
     It does not apply `TIMESTAMP' columns, which always require a
     valid date.

     This mode is new in MySQL 5.0.2. Before 5.0.2, this was the
     default MySQL date-handling mode. As of 5.0.2, enabling strict
     mode causes the server to require that month and day values be
     legal, not just in the range from 1 to 12 and 1 to 31. For
     example, `'2004-04-31'' is legal with strict mode disabled, but
     illegal with strict mode enabled. To allow such dates in strict
     mode, enable `ALLOW_INVALID_DATES' as well.

`ANSI_QUOTES'
     Treat `"' as an identifier quote character (like the ``' quote
     character) and not as a string quote character. You can still use
     ``' to quote identifers in ANSI mode. With `ANSI_QUOTES' enabled,
     you cannot use double quotes to quote a literal string, because it
     will be interpreted as an identifier.  (New in MySQL 4.0.0)

`ERROR_FOR_DIVISION_BY_ZERO'
     Produce an error in strict mode (otherwise a warning) when we
     encounter a division by zero (or `MOD(X,0)') during an `INSERT'/
     `UPDATE'. If this mode is not given, MySQL instead returns `NULL'
     for divisions by zero.  If used with `IGNORE', MySQL generates a
     warning for divisions by zero, but the result of the operation is
     `NULL'.  (New in MySQL 5.0.2)

`IGNORE_SPACE'
     Allow spaces between a function name and the `(' character.  This
     forces all function names to be treated as reserved words. As a
     result, if you want to access any database, table, or column name
     that is a reserved word, you must quote it.  For example, because
     there is a `USER()' function, the name of the `user' table in the
     `mysql' database and the `User' column in that table become
     reserved, so you must quote them:

          SELECT "User" FROM mysql."user";

     (New in MySQL 4.0.0)

`NO_AUTO_VALUE_ON_ZERO'
     `NO_AUTO_VALUE_ON_ZERO' affects handling of `AUTO_INCREMENT'
     columns. Normally, you generate the next sequence number for the
     column by inserting either `NULL' or `0' into it.
     `NO_AUTO_VALUE_ON_ZERO' suppresses this behavior for `0' so that
     only `NULL' generates the next sequence number.  (New in MySQL
     4.1.1)

     This mode can be useful if `0' has been stored in a table's
     `AUTO_INCREMENT' column. (This is not a recommended practice, by
     the way.)  For example, if you dump the table with `mysqldump' and
     then reload it, MySQL normally generates new sequence numbers when
     it encounters the `0' values, resulting in a table with different
     contents than the one that was dumped. Enabling
     `NO_AUTO_VALUE_ON_ZERO' before reloading the dump file solves this
     problem. As of MySQL 4.1.1, `mysqldump' automatically includes a
     statement in the dump output to enable `NO_AUTO_VALUE_ON_ZERO'.

`NO_DIR_IN_CREATE'
     When creating a table, ignore all `INDEX DIRECTORY' and `DATA
     DIRECTORY' directives. This option is useful on slave replication
     servers.  (New in MySQL 4.0.15)

`NO_FIELD_OPTIONS'
     Don't print MySQL-specific column options in the output of `SHOW
     CREATE TABLE'. This mode is used by `mysqldump' in portability
     mode.  (New in MySQL 4.1.1)

`NO_KEY_OPTIONS'
     Don't print MySQL-specific index options in the output of `SHOW
     CREATE TABLE'. This mode is used by `mysqldump' in portability
     mode.  (New in MySQL 4.1.1)

`NO_TABLE_OPTIONS'
     Don't print MySQL-specific table options (such as `ENGINE') in the
     output of `SHOW CREATE TABLE'. This mode is used by `mysqldump' in
     portability mode.  (New in MySQL 4.1.1)

`NO_ZERO_DATE'
     Don't allow `'0000-00-00'' as a valid date. You can still insert
     zero dates with the `IGNORE' option.  (New in MySQL 5.0.2)

`NO_ZERO_IN_DATE'
     Don't accept dates where the month or day part is 0. If used with
     the `IGNORE' option, we insert a `'0000-00-00'' date for any such
     date.  (New in MySQL 5.0.2)

`NO_UNSIGNED_SUBTRACTION'
     In subtraction operations, don't mark the result as `UNSIGNED' if
     one of the operands is unsigned. Note that this makes `UNSIGNED
     BIGINT' not 100% usable in all contexts. *Note Cast Functions::.
     (New in MySQL 4.0.2)

`ONLY_FULL_GROUP_BY'
     Don't allow queries that in the `GROUP BY' part refer to a not
     selected column.  (New in MySQL 4.0.0)

`PIPES_AS_CONCAT'
     Treat `||' as a string concatenation operator (same as `CONCAT()')
     rather than as a synonym for `OR'.  (New in MySQL 4.0.0)

`REAL_AS_FLOAT'
     Treat `REAL' as a synonym for `FLOAT' rather than as a synonym for
     `DOUBLE'.  (New in MySQL 4.0.0)

`STRICT_ALL_TABLES'
     Enable strict mode for all storage engines.  Invalid data values
     are rejected.  Additional detail follows.  (New in MySQL 5.0.2)

`STRICT_TRANS_TABLES'
     Enable strict mode for transactional storage engines, and when
     possible for non-transactional storage engines.  Additional detail
     follows.  (New in MySQL 5.0.2)

Strict mode controls how MySQL handles values that are invalid or
missing. A value can be invalid for several reasons.  For example, it
might have the wrong data type for the column, or it might be out of
range. A value is missing when a new row to be inserted does not
contain a value for a column that has no explicit `DEFAULT' clause in
its definition.

For transactional tables, an error occurs for invalid or missing values
in a statement when either of the `STRICT_ALL_TABLES' or
`STRICT_TRANS_TABLES' modes are enabled.  The statement is aborted and
rolled back.

For non-transactional tables, the behavior is the same for either mode,
if the bad value occurs in the first row to be inserted or updated.
The statement is aborted and the table remains unchanged.  If the
statement inserts or modifies multiple rows and the bad value occurs in
the second or later row, the result depends on which strict option is
enabled:

   * For `STRICT_ALL_TABLES', MySQL returns an error and ignores the
     rest of the rows. However, in this case, the earlier rows will
     already have been inserted or updated.  This means that you might
     get a partial update, which might not be what you want.  To avoid
     this, it's best to use single-row statements because these can be
     aborted without changing the table.

   * For `STRICT_TRANS_TABLES', MySQL converts an invalid value to the
     closest valid value for the column and insert the adjusted value.
     If a value is missing, MySQL inserts the implicit default value
     for the column data type.  In either case, MySQL generates a
     warning rather than an error and continues processing the
     statement. Implicit defaults are described in *Note `CREATE
     TABLE': CREATE TABLE.


Strict mode disallows invalid date values such as `'2004-04-31''.  It
does not disallow dates with zero parts such as `2004-04-00'' or "zero"
dates. To disallow these as well, enable the `NO_ZERO_IN_DATE' and
`NO_ZERO_DATE' SQL modes in addition to strict mode.

If you are not using strict mode (that is, neither `STRICT_TRANS_TABLES'
nor `STRICT_ALL_TABLES' is enabled), MySQL inserts adjusted values for
invalid or missing values and produces warnings.  In strict mode, you
can produce this behavior by using `INSERT IGNORE' or `UPDATE IGNORE'.
*Note `SHOW WARNINGS': SHOW WARNINGS.

The following special modes are provided as shorthand for combinations
of mode values from the preceding list.  All are available as of MySQL
4.1.1, except `TRADITIONAL' (5.0.2).

`ANSI'
     Equivalent to `REAL_AS_FLOAT', `PIPES_AS_CONCAT', `ANSI_QUOTES',
     `IGNORE_SPACE', `ONLY_FULL_GROUP_BY'. *Note ANSI mode::.

`DB2'
     Equivalent to `PIPES_AS_CONCAT', `ANSI_QUOTES', `IGNORE_SPACE',
     `NO_KEY_OPTIONS', `NO_TABLE_OPTIONS', `NO_FIELD_OPTIONS'.

`MAXDB'
     Equivalent to `PIPES_AS_CONCAT', `ANSI_QUOTES', `IGNORE_SPACE',
     `NO_KEY_OPTIONS', `NO_TABLE_OPTIONS', `NO_FIELD_OPTIONS'.

`MSSQL'
     Equivalent to `PIPES_AS_CONCAT', `ANSI_QUOTES', `IGNORE_SPACE',
     `NO_KEY_OPTIONS', `NO_TABLE_OPTIONS', `NO_FIELD_OPTIONS'.

`MYSQL323'
     Equivalent to `NO_FIELD_OPTIONS'.

`MYSQL40'
     Equivalent to `NO_FIELD_OPTIONS'.

`ORACLE'
     Equivalent to `PIPES_AS_CONCAT', `ANSI_QUOTES', `IGNORE_SPACE',
     `NO_KEY_OPTIONS', `NO_TABLE_OPTIONS', `NO_FIELD_OPTIONS'.

`POSTGRESQL'
     Equivalent to `PIPES_AS_CONCAT', `ANSI_QUOTES', `IGNORE_SPACE',
     `NO_KEY_OPTIONS', `NO_TABLE_OPTIONS', `NO_FIELD_OPTIONS'.

`TRADITIONAL'
     Equivalent to `STRICT_TRANS_TABLES', `STRICT_ALL_TABLES',
     `NO_ZERO_IN_DATE', `NO_ZERO_DATE', `ERROR_FOR_DIVISION_BY_ZERO'.

Server System Variables
-----------------------

The server maintains many system variables that indicate how it is
configured.  All of them have default values. They can be set at server
startup using options on the command line or in option files. Most of
them can be set at runtime using the `SET' statement.

Beginning with MySQL 4.0.3, the `mysqld' server maintains two kinds of
variables.  Global variables affect the overall operation of the server.
Session variables affect its operation for individual client
connections.

When the server starts, it initializes all global variables to their
default values. These defaults can be changed by options specified in
option files or on the command line.  After the server starts, those
global variables that are dynamic can be changed by connecting to the
server and issuing a `SET GLOBAL VAR_NAME' statement. To change a
global variable, you must have the `SUPER' privilege.

The server also maintains a set of session variables for each client
that connects. The client's session variables are initialized at connect
time using the current values of the corresponding global variables. For
those session variables that are dynamic, the client can change them by
issuing a `SET SESSION VAR_NAME' statement. Setting a session variable
requires no special privilege, but a client can change only its own
session variables, not those of any other client.

A change to a global variable is visible to any client that accesses
that global variable. However, it affects the corresponding session
variable that is initialized from the global variable only for clients
that connect after the change.  It does not affect the session variable
for any client that is already connected (not even that of the client
that issues the `SET GLOBAL' statement).

When setting a variable using a startup option, variable values can be
given with a suffix of `K', `M', or `G' to indicate kilobytes,
megabytes, or gigabytes, respectively. For example, the following
command starts the server with a key buffer size of 16 megabytes:

     mysqld --key_buffer_size=16M

Before MySQL 4.0, use this syntax instead:

     mysqld --set-variable=key_buffer_size=16M

The lettercase of suffix letters does not matter; `16M' and `16m' are
equivalent.

At runtime, use the `SET' statement to set system variables. In this
context, suffix letters cannot be used, but the value can take the form
of an expression:

     mysql> SET sort_buffer_size = 10 * 1024 * 1024;

To specify explicitly whether to set the global or session variable,
use the `GLOBAL' or `SESSION' options:

     mysql> SET GLOBAL sort_buffer_size = 10 * 1024 * 1024;
     mysql> SET SESSION sort_buffer_size = 10 * 1024 * 1024;

Without either option, the statement sets the session variable.

The variables that can be set at runtime are listed in *Note Dynamic
System Variables::.

If you want to restrict the maximum value to which a system variable can
be set with the `SET' statement, you can specify this maximum by using
an option of the form `--maximum-VAR_NAME' at server startup. For
example, to prevent the value of `query_cache_size' from being
increased to more than 32MB at runtime, use the option
`--maximum-query_cache_size=32M'. This feature is available as of MySQL
4.0.2.

You can view system variables and their values by using the `SHOW
VARIABLES' statement.  See *Note System Variables:: for more
information.

     mysql> SHOW VARIABLES;
     +---------------------------------+------------------------------+
     | Variable_name                   | Value                        |
     +---------------------------------+------------------------------|
     | back_log                        | 50                           |
     | basedir                         | /usr/local/mysql             |
     | bdb_cache_size                  | 8388572                      |
     | bdb_home                        | /usr/local/mysql             |
     | bdb_log_buffer_size             | 32768                        |
     | bdb_logdir                      |                              |
     | bdb_max_lock                    | 10000                        |
     | bdb_shared_data                 | OFF                          |
     | bdb_tmpdir                      | /tmp/                        |
     | bdb_version                     | Sleepycat Software: ...      |
     | binlog_cache_size               | 32768                        |
     | bulk_insert_buffer_size         | 8388608                      |
     | character_set                   | latin1                       |
     | character_sets                  | latin1 big5 czech euc_kr     |
     | concurrent_insert               | ON                           |
     | connect_timeout                 | 5                            |
     | convert_character_set           |                              |
     | datadir                         | /usr/local/mysql/data/       |
     | default_week_format             | 0                            |
     | delay_key_write                 | ON                           |
     | delayed_insert_limit            | 100                          |
     | delayed_insert_timeout          | 300                          |
     | delayed_queue_size              | 1000                         |
     | flush                           | OFF                          |
     | flush_time                      | 0                            |
     | ft_boolean_syntax               | + -><()~*:""&|               |
     | ft_max_word_len                 | 84                           |
     | ft_min_word_len                 | 4                            |
     | ft_query_expansion_limit        | 20                           |
     | ft_stopword_file                | (built-in)                   |
     | have_bdb                        | YES                          |
     | have_innodb                     | YES                          |
     | have_isam                       | YES                          |
     | have_openssl                    | YES                          |
     | have_query_cache                | YES                          |
     | have_raid                       | NO                           |
     | have_symlink                    | DISABLED                     |
     | init_file                       |                              |
     | innodb_additional_mem_pool_size | 1048576                      |
     | innodb_buffer_pool_size         | 8388608                      |
     | innodb_data_file_path           | ibdata1:10M:autoextend       |
     | innodb_data_home_dir            |                              |
     | innodb_fast_shutdown            | ON                           |
     | innodb_file_io_threads          | 4                            |
     | innodb_flush_log_at_trx_commit  | 1                            |
     | innodb_flush_method             |                              |
     | innodb_force_recovery           | 0                            |
     | innodb_lock_wait_timeout        | 50                           |
     | innodb_log_arch_dir             |                              |
     | innodb_log_archive              | OFF                          |
     | innodb_log_buffer_size          | 1048576                      |
     | innodb_log_file_size            | 5242880                      |
     | innodb_log_files_in_group       | 2                            |
     | innodb_log_group_home_dir       | ./                           |
     | innodb_mirrored_log_groups      | 1                            |
     | innodb_thread_concurrency       | 8                            |
     | interactive_timeout             | 28800                        |
     | join_buffer_size                | 131072                       |
     | key_buffer_size                 | 16773120                     |
     | key_cache_age_threshold         | 300                          |
     | key_cache_block_size            | 1024                         |
     | key_cache_division_limit        | 100                          |
     | language                        | /usr/local/mysql/share/...   |
     | large_files_support             | ON                           |
     | local_infile                    | ON                           |
     | locked_in_memory                | OFF                          |
     | log                             | OFF                          |
     | log_bin                         | OFF                          |
     | log_slave_updates               | OFF                          |
     | log_slow_queries                | OFF                          |
     | log_update                      | OFF                          |
     | log_warnings                    | 1                            |
     | long_query_time                 | 10                           |
     | low_priority_updates            | OFF                          |
     | lower_case_table_names          | 0                            |
     | max_allowed_packet              | 1047552                      |
     | max_binlog_cache_size           | 4294967295                   |
     | max_binlog_size                 | 1073741824                   |
     | max_connect_errors              | 10                           |
     | max_connections                 | 100                          |
     | max_delayed_threads             | 20                           |
     | max_error_count                 | 64                           |
     | max_heap_table_size             | 16777216                     |
     | max_join_size                   | 4294967295                   |
     | max_relay_log_size              | 0                            |
     | max_sort_length                 | 1024                         |
     | max_tmp_tables                  | 32                           |
     | max_user_connections            | 0                            |
     | max_write_lock_count            | 4294967295                   |
     | myisam_max_extra_sort_file_size | 268435456                    |
     | myisam_max_sort_file_size       | 2147483647                   |
     | myisam_recover_options          | force                        |
     | myisam_repair_threads           | 1                            |
     | myisam_sort_buffer_size         | 8388608                      |
     | net_buffer_length               | 16384                        |
     | net_read_timeout                | 30                           |
     | net_retry_count                 | 10                           |
     | net_write_timeout               | 60                           |
     | open_files_limit                | 1024                         |
     | pid_file                        | /usr/local/mysql/name.pid    |
     | port                            | 3306                         |
     | protocol_version                | 10                           |
     | query_cache_limit               | 1048576                      |
     | query_cache_size                | 0                            |
     | query_cache_type                | ON                           |
     | read_buffer_size                | 131072                       |
     | read_rnd_buffer_size            | 262144                       |
     | rpl_recovery_rank               | 0                            |
     | server_id                       | 0                            |
     | skip_external_locking           | ON                           |
     | skip_networking                 | OFF                          |
     | skip_show_database              | OFF                          |
     | slave_net_timeout               | 3600                         |
     | slow_launch_time                | 2                            |
     | socket                          | /tmp/mysql.sock              |
     | sort_buffer_size                | 2097116                      |
     | sql_mode                        |                              |
     | table_cache                     | 64                           |
     | table_type                      | MYISAM                       |
     | thread_cache_size               | 3                            |
     | thread_stack                    | 131072                       |
     | timezone                        | EEST                         |
     | tmp_table_size                  | 33554432                     |
     | tmpdir                          | /tmp/:/mnt/hd2/tmp/          |
     | tx_isolation                    | READ-COMMITTED               |
     | version                         | 4.0.4-beta                   |
     | wait_timeout                    | 28800                        |
     +---------------------------------+------------------------------+

Most system variables are described here.  Variables with no version
indicated have been present since at least MySQL 3.22.  `InnoDB' system
variables are listed at *Note `InnoDB' start: InnoDB start.

Values for buffer sizes, lengths, and stack sizes are given in bytes
unless otherwise specified.

Information on tuning these variables can be found in *Note Server
parameters::.

`ansi_mode'
     This is `ON' if `mysqld' was started with `--ansi'.  *Note ANSI
     mode::.  This variable was added in MySQL 3.23.6 and removed in
     3.23.41.  See the description for `sql_mode'.

`back_log'
     The number of outstanding connection requests MySQL can have. This
     comes into play when the main MySQL thread gets very many
     connection requests in a very short time. It then takes some time
     (although very little) for the main thread to check the connection
     and start a new thread. The `back_log' value indicates how many
     requests can be stacked during this short time before MySQL
     momentarily stops answering new requests. You need to increase
     this only if you expect a large number of connections in a short
     period of time.

     In other words, this value is the size of the listen queue for
     incoming TCP/IP connections.  Your operating system has its own
     limit on the size of this queue.  The manual page for the Unix
     `listen()' system call should have more details.  Check your OS
     documentation for the maximum value for this variable.  Attempting
     to set `back_log' higher than your operating system limit will be
     ineffective.

`basedir'
     The MySQL installation base directory. This variable can be set
     with the `--basedir' option.

`bdb_cache_size'
     The size of the buffer that is allocated for caching indexes and
     rows for `BDB' tables.  If you don't use `BDB' tables, you should
     start `mysqld' with `--skip-bdb' to not waste memory for this
     cache.  This variable was added in MySQL 3.23.14.

`bdb_home'
     The base directory for `BDB' tables.  This should be assigned the
     same value as the `datadir' variable.  This variable was added in
     MySQL 3.23.14.

`bdb_log_buffer_size'
     The size of the buffer that is allocated for caching indexes and
     rows for `BDB' tables.  If you don't use `BDB' tables, you should
     set this to 0 or start `mysqld' with `--skip-bdb' to not waste
     memory for this cache.  This variable was added in MySQL 3.23.31.

`bdb_logdir'
     The directory where the `BDB' storage engine writes its log files.
     This variable can be set with the `--bdb-logdir' option.  This
     variable was added in MySQL 3.23.14.

`bdb_max_lock'
     The maximum number of locks you can have active on a `BDB' table
     (10,000 by default). You should increase this if errors such as the
     following occur when you perform long transactions or when
     `mysqld' has to examine many rows to calculate a query:

          bdb: Lock table is out of available locks
          Got error 12 from ...

     This variable was added in MySQL 3.23.29.

`bdb_shared_data'
     This is `ON' if you are using `--bdb-shared-data'.  This variable
     was added in MySQL 3.23.29.

`bdb_tmpdir'
     The value of the `--bdb-tmpdir' option.  This variable was added
     in MySQL 3.23.14.

`bdb_version'
     See the description for `version_bdb'.

`binlog_cache_size'
     The size of the cache to hold the SQL statements for the binary
     log during a transaction.  A binary log cache is allocated for
     each client if the server supports any transactional storage
     engines and, starting from MySQL 4.1.2, if the server has binary
     log enabled (`--log-bin' option). If you often use big,
     multiple-statement transactions, you can increase this to get more
     performance.  The `Binlog_cache_use' and `Binlog_cache_disk_use'
     status variables can be useful for tuning the size of this
     variable.  This variable was added in MySQL 3.23.29.  *Note Binary
     log::.

`bulk_insert_buffer_size'
     `MyISAM' uses a special tree-like cache to make bulk inserts
     faster for `INSERT ... SELECT', `INSERT ... VALUES (...), (...),
     ...', and `LOAD DATA INFILE'. This variable limits the size of the
     cache tree in bytes per thread. Setting it to 0 disables this
     optimization.  *Note*: This cache is used only when adding data to
     a non-empty table.  The default value is 8MB.  This variable was
     added in MySQL 4.0.3.  This variable previously was named
     `myisam_bulk_insert_tree_size'.

`character_set'
     The default character set.  This variable was added in MySQL
     3.23.3, then removed in MySQL 4.1.1 and replaced by the various
     `character_set_XXX' variables.

`character_set_client'
     The character set for statements that arrive from the client.
     This variable was added in MySQL 4.1.1.

`character_set_connection'
     The character set used for literals that do not have a character
     set introducer and for number-to-string conversion.  This variable
     was added in MySQL 4.1.1.

`character_set_database'
     The character set used by the default database.  The server sets
     this variable whenever the default database changes.  If there is
     no default database, the variable has the same value as
     `character_set_server'.  This variable was added in MySQL 4.1.1.

`character_set_results'
     The character set used for returning query results to the client.
     This variable was added in MySQL 4.1.1.

`character_set_server'
     The server default character set.  This variable was added in
     MySQL 4.1.1.

`character_set_system'
     The character set used by the server for storing identifiers.  The
     value is always `utf8'.  This variable was added in MySQL 4.1.1.

`character_sets'
     The supported character sets.  This variable was added in MySQL
     3.23.15 and removed in MySQL 4.1.1.  (Use `SHOW CHARACTER SET' for
     a list of character sets.)

`character_sets_dir'
     The directory where character sets are installed.  This variable
     was added in MySQL 4.1.2.

`collation_connection'
     The collation of the connection character set.  This variable was
     added in MySQL 4.1.1.

`collation_database'
     The collation used by the default database.  The server sets this
     variable whenever the default database changes.  If there is no
     default database, the variable has the same value as
     `collation_server'.  This variable was added in MySQL 4.1.1.

`collation_server'
     The server default collation.  This variable was added in MySQL
     4.1.1.

`concurrent_insert'
     If `ON' (the default), MySQL allows `INSERT' and `SELECT'
     statements to run concurrently for `MyISAM' tables that have no
     free blocks in the middle.  You can turn this option off by
     starting `mysqld' with `--safe' or `--skip-new'.  This variable
     was added in MySQL 3.23.7.

`connect_timeout'
     The number of seconds the `mysqld' server waits for a connect
     packet before responding with `Bad handshake'.

`convert_character_set'
     The current character set mapping that was set by `SET CHARACTER
     SET'.  This variable was removed in MySQL 4.1.

`datadir'
     The MySQL data directory. This variable can be set with the
     `--datadir' option.

`default_week_format'
     The default mode value to use for the `WEEK()' function.  This
     variable is available as of MySQL 4.0.14.

`delay_key_write'
     This option applies only to `MyISAM' tables. It can have one of the
     following values to affect handling of the `DELAY_KEY_WRITE' table
     option that can be used in `CREATE TABLE' statements.

     *Option**Description*
     `OFF'   `DELAYED_KEY_WRITE' is ignored.
     `ON'    MySQL honors the `DELAY_KEY_WRITE' option for
             `CREATE TABLE'. This is the default value.
     `ALL'   All new opened tables are treated as if they were
             created with the `DELAY_KEY_WRITE' option enabled.

     If `DELAY_KEY_WRITE' is enabled, this means that the key buffer for
     tables with this option are not flushed on every index update, but
     only when a table is closed.  This will speed up writes on keys a
     lot, but if you use this feature, you should add automatic
     checking of all `MyISAM' tables by starting the server with the
     `--myisam-recover' option (for example,
     `--myisam-recover=BACKUP,FORCE').  See *Note Server options:: and
     *Note MyISAM start::.

     Note that `--external-locking' doesn't offer any protection against
     index corruption for tables that use delayed key writes.

     This variable was added in MySQL 3.23.8.

`delayed_insert_limit'
     After inserting `delayed_insert_limit' delayed rows, the `INSERT
     DELAYED' handler thread checks whether there are any `SELECT'
     statements pending. If so, it allows them to execute before
     continuing to insert delayed rows.

`delayed_insert_timeout'
     How long an `INSERT DELAYED' handler thread should wait for
     `INSERT' statements before terminating.

`delayed_queue_size'
     This is a per-table limit on the number of rows to queue when
     handling `INSERT DELAYED' statements.  If the queue becomes full,
     any client that issues an `INSERT DELAYED' statement will wait
     until there is room in the queue again.

`expire_logs_days'
     The number of days for automatic binary log removal.  The default
     is 0, which means "no automatic removal."  This variable was added
     in MySQL 4.1.0.

`flush'
     This is `ON' if you have started `mysqld' with the `--flush'
     option.  This variable was added in MySQL 3.22.9.

`flush_time'
     If this is set to a non-zero value, all tables will be closed every
     `flush_time' seconds to free up resources and sync unflushed data
     to disk.  We recommend this option only on Windows 9x or Me, or on
     systems with minimal resources available.  This variable was added
     in MySQL 3.22.18.

`ft_boolean_syntax'
     The list of operators supported by boolean full-text searches
     performed using `IN BOOLEAN MODE'.  This variable was added in
     MySQL 4.0.1.  *Note Fulltext Boolean::.

     The default variable value is `'+ -><()~*:""&|''. The rules for
     changing the value are as follows:

        * Operator function is determined by position within the string.

        * The replacement value must be 14 characters.

        * Each character must be an ASCII non-alphanumeric character.

        * Either the first or second character must be a space.

        * No duplicates are allowed except the phrase quoting operators
          in positions 11 and 12. These two characters are not required
          to be the same, but they are the only two that may be.

        * Positions 10, 13, and 14 (which by default are set to `:',
          `&', and `|') are reserved for future extensions.


`ft_max_word_len'
     The maximum length of the word to be included in a `FULLTEXT'
     index.  This variable was added in MySQL 4.0.0.

     *Note*: `FULLTEXT' indexes must be rebuilt after changing this
     variable.  Use `REPAIR TABLE TBL_NAME QUICK'.

`ft_min_word_len'
     The minimum length of the word to be included in a `FULLTEXT'
     index.  This variable was added in MySQL 4.0.0.

     *Note*: `FULLTEXT' indexes must be rebuilt after changing this
     variable.  Use `REPAIR TABLE TBL_NAME QUICK'.

`ft_query_expansion_limit'
     The number of top matches to use for full-text searches performed
     using `WITH QUERY EXPANSION'.  This variable was added in MySQL
     4.1.1.

`ft_stopword_file'
     The file from which to read the list of stopwords for full-text
     searches.  All the words from the file are used; comments are
     _not_ honored.  By default, a built-in list of stopwords is used
     (as defined in the `myisam/ft_static.c' file).  Setting this
     variable to the empty string (`''') disables stopword filtering.
     This variable was added in MySQL 4.0.10.

     *Note*: `FULLTEXT' indexes must be rebuilt after changing this
     variable.  Use `REPAIR TABLE TBL_NAME QUICK'.

`group_concat_max_len'
     The maximum allowed result length for the `GROUP_CONCAT()'
     function.  This variable was added in MySQL 4.1.0.

`have_archive'
     `YES' if `mysqld' supports `ARCHIVE' tables.  This variable was
     added in MySQL 4.1.3.

`have_bdb'
     `YES' if `mysqld' supports `BDB' tables. `DISABLED' if
     `--skip-bdb' is used.  This variable was added in MySQL 3.23.30.

`have_compress'
     Whether the `zlib' compression library is available to the server.
     If not, the `COMPRESS()' and `UNCOMPRESS()' functions cannot be
     used.  This variable was added in MySQL 4.1.1.

`have_crypt'
     Whether the `crypt()' system call is available to the server.  If
     not, the `CRYPT()' function cannot be used.  This variable was
     added in MySQL 4.0.10.

`have_geometry'
     Whether the server supports spatial data types.  This variable was
     added in MySQL 4.1.3.

`have_innodb'
     `YES' if `mysqld' supports `InnoDB' tables. `DISABLED' if
     `--skip-innodb' is used.  This variable was added in MySQL 3.23.37.

`have_isam'
     `YES' if `mysqld' supports `ISAM' tables. `DISABLED' if
     `--skip-isam' is used.  This variable was added in MySQL 3.23.30.

`have_ndbcluster'
     `YES' if `mysqld' supports `NDB Cluster' tables.  `DISABLED' if
     `--skip-ndbcluster' is used.  This variable was added in MySQL
     4.1.2.

`have_openssl'
     `YES' if `mysqld' supports SSL (encryption) of the client/server
     protocol.  This variable was added in MySQL 3.23.43.

`have_query_cache'
     `YES' if `mysqld' supports the query cache.  This variable was
     added in MySQL 4.0.2.

`have_raid'
     `YES' if `mysqld' supports the `RAID' option.  This variable was
     added in MySQL 3.23.30.

`have_rtree_keys'
     Whether `RTREE' indexes are available. (These are used for spatial
     indexed in `MyISAM' tables.)  This variable was added in MySQL
     4.1.3.

`have_symlink'
     Whether symbolic link support is enabled. This is required on Unix
     for support of the `DATA DIRECTORY' and `INDEX DIRECTORY' table
     options.  This variable was added in MySQL 4.0.0.

`init_connect'
     A string to be executed by the server for each client that
     connects.  The string consists of one or more SQL statements. To
     specify multiple statements, separate them by semicolon characters.
     For example, each client begins by default with autocommit mode
     enabled.  There is no global server variable to specify that
     autocommit should be disabled by default, but `init_connect' can
     be used to achieve the same effect:

          SET GLOBAL init_connect='SET AUTOCOMMIT=0';

     This variable can also be set on the command line or in an option
     file.  To set the variable as just shown using an option file,
     include these lines:

          [mysqld]
          init_connect='SET AUTOCOMMIT=0'

     Note that the content of `init_connect' is not executed for users
     having the `SUPER' privilege; this is in case that content has
     been wrongly set (contains a wrong query, for example with a
     syntax error), thus making all connections fail. Not executing it
     for `SUPER' users enables those to open a connection and fix
     `init_connect'.  This variable was added in MySQL 4.1.2.

`init_file'
     The name of the file specified with the `--init-file' option when
     you start the server.  This is a file containing SQL statements
     that you want the server to execute when it starts.  Each
     statement must be on a single line and should not include comments.
     This variable was added in MySQL 3.23.2.

`init_slave'
     This variable is similar to `init_connect', but is a string to be
     executed by a slave server each time the SQL thread starts.  The
     format of the string is the same as for the `init_connect'
     variable.  This variable was added in MySQL 4.1.2.

`innodb_XXX'
     The `InnoDB' system variables are listed at *Note `InnoDB' start:
     InnoDB start.

`interactive_timeout'
     The number of seconds the server waits for activity on an
     interactive connection before closing it.  An interactive client
     is defined as a client that uses the `CLIENT_INTERACTIVE' option to
     `mysql_real_connect()'.  See also `wait_timeout'.

`join_buffer_size'
     The size of the buffer that is used for full joins (joins that do
     not use indexes).  Normally the best way to get fast joins is to
     add indexes.  Increase the value of `join_buffer_size' to get a
     faster full join when adding indexes is not possible.  One join
     buffer is allocated for each full join between two tables. For a
     complex join between several tables for which indexes are not
     used, multiple join buffers might be necessary.

`key_buffer_size'
     Index blocks for `MyISAM' and `ISAM' tables are buffered and are
     shared by all threads.  `key_buffer_size' is the size of the buffer
     used for index blocks.  The key buffer is also known as the key
     cache.

     The maximum allowable setting for `key_buffer_size' is 4GB. The
     effective maximum size might be less, depending on your available
     physical RAM and per-process RAM limits imposed by your operating
     system or hardware platform.

     Increase the value to get better index handling (for all reads and
     multiple writes) to as much as you can afford. Using a value that
     is 25% of total memory on a machine that mainly runs MySQL is
     quite common.  However, if you make the value too large (for
     example, more than 50% of your total memory) your system might
     start to page and become extremely slow.  MySQL relies on the
     operating system to perform filesystem caching for data reads, so
     you must leave some room for the filesystem cache.

     For even more speed when writing many rows at the same time, use
     `LOCK TABLES'.  *Note `LOCK TABLES': LOCK TABLES.

     You can check the performance of the key buffer by issuing a `SHOW
     STATUS' statement and examining the `Key_read_requests',
     `Key_reads', `Key_write_requests', and `Key_writes' status
     variables.  *Note `SHOW': SHOW.

     The `Key_reads/Key_read_requests' ratio should normally be less
     than 0.01.  The `Key_writes/Key_write_requests' ratio is usually
     near 1 if you are using mostly updates and deletes, but might be
     much smaller if you tend to do updates that affect many rows at
     the same time or if you are using the `DELAY_KEY_WRITE' table
     option.

     The fraction of the key buffer in use can be determined using
     `key_buffer_size' in conjunction with the `Key_blocks_used' status
     variable and the buffer block size.  From MySQL 4.1.1 on, the
     buffer block size is available from the `key_cache_block_size'
     server variable. The fraction of the buffer in use is:

          (Key_blocks_used * key_cache_block_size) / key_buffer_size

     Before MySQL 4.1.1, key cache blocks are 1024 bytes, so the
     fraction of the key buffer in use is:

          (Key_blocks_used * 1024) / key_buffer_size

     *Note `MyISAM' key cache: MyISAM key cache.

`key_cache_age_threshold'
     This value controls the demotion of buffers from the hot sub-chain
     of a key cache to the warm sub-chain.  Lower values cause demotion
     to happen more quickly.  The minimum value is 100.  The default
     value is 300.  This variable was added in MySQL 4.1.1.  *Note
     `MyISAM' key cache: MyISAM key cache.

`key_cache_block_size'
     The size in bytes of blocks in the key cache.  The default value
     is 1024.  This variable was added in MySQL 4.1.1.  *Note `MyISAM'
     key cache: MyISAM key cache.

`key_cache_division_limit'
     The division point between the hot and warm sub-chains of the key
     cache buffer chain. The value is the percentage of the buffer
     chain to use for the warm sub-chain.  Allowable values range from
     1 to 100.  The default value is 100.  This variable was added in
     MySQL 4.1.1.  *Note `MyISAM' key cache: MyISAM key cache.

`language'
     The language used for error messages.

`large_file_support'
     Whether `mysqld' was compiled with options for large file support.
     This variable was added in MySQL 3.23.28.

`license'
     The type of license the server has.  This variable was added in
     MySQL 4.0.19.

`local_infile'
     Whether `LOCAL' is supported for `LOAD DATA INFILE' statements.
     This variable was added in MySQL 4.0.3.

`locked_in_memory'
     Whether `mysqld' was locked in memory with `--memlock'.  This
     variable was added in MySQL 3.23.25.

`log'
     Whether logging of all queries to the general query log is enabled.
     *Note Query log::.

`log_bin'
     Whether the binary log is enabled.  This variable was added in
     MySQL 3.23.14.  *Note Binary log::.

`log_error'
     The location of the error log.  This variable was added in MySQL
     4.0.10.

`log_slave_updates'
     Whether updates received by a slave server from a master server
     should be logged to the slave's own binary log. Binary logging
     must be enabled on the slave for this to have any effect.  This
     variable was added in MySQL 3.23.17.  *Note Replication Options::.

`log_slow_queries'
     Whether slow queries should be logged.  "Slow" is determined by
     the value of the `long_query_time' variable.  This variable was
     added in MySQL 4.0.2.  *Note Slow query log::.

`log_update'
     Whether the update log is enabled.  This variable was added in
     MySQL 3.22.18.  Note that the binary log is preferable to the
     update log, which is unavailable as of MySQL 5.0.  *Note Update
     log::.

`log_warnings'
     Whether to produce additional warning messages.  This variable was
     added in MySQL 4.0.3.  It is enabled by default as of MySQL 4.0.19
     and 4.1.2.  As of MySQL 4.0.21 and 4.1.3, aborted connections are
     not logged to the error log unless the value is greater than 1.

`long_query_time'
     If a query takes longer than this many seconds, the `Slow_queries'
     status variable is incremented. If you are using the
     `--log-slow-queries' option, the query is logged to the slow query
     log file. This value is measured in real time, not CPU time, so a
     query that is under the threshold on a lightly loaded system might
     be above the threshold on a heavily loaded one.  *Note Slow query
     log::.

`low_priority_updates'
     If set to `1', all `INSERT', `UPDATE', `DELETE', and `LOCK TABLE
     WRITE' statements wait until there is no pending `SELECT' or `LOCK
     TABLE READ' on the affected table.  This variable previously was
     named `sql_low_priority_updates'.  It was added in MySQL 3.22.5.

`lower_case_file_system'
     This variable indicates whether the filesystem where the data
     directory is located has case insensitive filenames.  `ON' means
     filenames are case insensitive, `OFF' means they are case
     sensitive.  This variable was added in MySQL 4.0.19.

`lower_case_table_names'
     If set to 1, table names are stored in lowercase on disk and table
     name comparisons are not case sensitive.  This variable was added
     in MySQL 3.23.6.  If set to 2 (new in 4.0.18), table names are
     stored as given but compared in lowercase.  From MySQL 4.0.2, this
     option also applies to database names.  From 4.1.1, it also
     applies to table aliases.  *Note Name case sensitivity::.

     You should _not_ set this variable to 0 if you are running MySQL
     on a system that does not have case-sensitive filenames (such as
     Windows or Mac OS X).  New in 4.0.18:  If this variable is not set
     at startup and the filesystem on which the data directory is
     located does not have case-sensitive filenames, MySQL
     automatically sets `lower_case_table_names' to 2.

`max_allowed_packet'
     The maximum size of one packet or any generated/intermediate
     string.

     The packet message buffer is initialized to `net_buffer_length'
     bytes, but can grow up to `max_allowed_packet' bytes when needed.
     This value by default is small, to catch big (possibly wrong)
     packets.

     You must increase this value if you are using big `BLOB' columns or
     long strings. It should be as big as the biggest `BLOB' you want to
     use.  The protocol limit for `max_allowed_packet' is 16MB before
     MySQL 4.0 and 1GB thereafter.

`max_binlog_cache_size'
     If a multiple-statement transaction requires more than this amount
     of memory, you will get the error `Multi-statement transaction
     required more than 'max_binlog_cache_size' bytes of storage'.
     This variable was added in MySQL 3.23.29.

`max_binlog_size'
     If a write to the binary log exceeds the given value, rotate the
     binary logs.  You cannot set this variable to more than 1GB or to
     less than 4096 bytes.  (The minimum before MYSQL 4.0.14 is 1024
     bytes.) The default value is 1GB.  This variable was added in
     MySQL 3.23.33.

     Note if you are using transactions: A transaction is written in
     one chunk to the binary log, hence it is never split between
     several binary logs.  Therefore, if you have big transactions, you
     might see binary logs bigger than `max_binlog_size'.

     If `max_relay_log_size' is 0, the value of `max_binlog_size'
     applies to relay logs as well. `max_relay_log_size' was added in
     MySQL 4.0.14.

`max_connect_errors'
     If there are more than this number of interrupted connections from
     a host, that host is blocked from further connections.  You can
     unblock blocked hosts with the `FLUSH HOSTS' statement.

`max_connections'
     The number of simultaneous client connections allowed. Increasing
     this value increases the number of file descriptors that `mysqld'
     requires.  See *Note Table cache:: for comments on file descriptor
     limits.  Also see *Note Too many connections::.

`max_delayed_threads'
     Don't start more than this number of threads to handle `INSERT
     DELAYED' statements.  If you try to insert data into a new table
     after all `INSERT DELAYED' threads are in use, the row will be
     inserted as if the `DELAYED' attribute wasn't specified. If you
     set this to 0, MySQL never creates a thread to handle `DELAYED'
     rows; in effect, this disables `DELAYED' entirely.  This variable
     was added in MySQL 3.23.0.

`max_error_count'
     The maximum number of error, warning, and note messages to be
     stored for display by `SHOW ERRORS' or `SHOW WARNINGS'.  This
     variable was added in MySQL 4.1.0.

`max_heap_table_size'
     This variable sets the maximum size to which `MEMORY' (`HEAP')
     tables are allowed to grow.  The value of the variable is used to
     calculate `MEMORY' table `MAX_ROWS' values.  Setting this variable
     has no effect on any existing `MEMORY' table, unless the table is
     re-created with a statement such as `CREATE TABLE' or `TRUNCATE
     TABLE', or altered with `ALTER TABLE'.  This variable was added in
     MySQL 3.23.0.

`max_insert_delayed_threads'
     This variable is a synonym for `max_delayed_threads'.  It was
     added in MySQL 4.0.19.

`max_join_size'
     Don't allow `SELECT' statements that probably will need to examine
     more than `max_join_size' row combinations or are likely to do more
     than `max_join_size' disk seeks.  By setting this value, you can
     catch `SELECT' statements where keys are not used properly and
     that would probably take a long time.  Set it if your users tend
     to perform joins that lack a `WHERE' clause, that take a long
     time, or that return millions of rows.

     Setting this variable to a value other than `DEFAULT' resets the
     `SQL_BIG_SELECTS' value to `0'.  If you set the `SQL_BIG_SELECTS'
     value again, the `max_join_size' variable is ignored.

     If a query result already is in the query cache, no result size
     check is performed, because the result has already been computed
     and it does not burden the server to send it to the client.

     This variable previously was named `sql_max_join_size'.

`max_length_for_sort_data'
     The cutoff on the size of index values that determines which
     `filesort' algorithm to use.  *Note `ORDER BY' optimization: ORDER
     BY optimization.  This variable was added in MySQL 4.1.1

`max_relay_log_size'
     If a write by a replication slave to its relay log exceeds the
     given value, rotate the relay log.  This variable enables you to
     put different size constraints on relay logs and binary logs.
     However, setting the variable to 0 makes MySQL use
     `max_binlog_size' for both binary logs and relay logs.  You must
     set `max_relay_log_size' to between 4096 bytes and 1GB
     (inclusive), or to 0. The default value is 0.  This variable was
     added in MySQL 4.0.14.  *Note Replication Implementation Details::.

`max_seeks_for_key'
     Limit the assumed maximum number of seeks when looking up rows
     based on a key.  The MySQL optimizer will assume that no more than
     this number of key seeks will be required when searching for
     matching rows in a table by scanning a key, regardless of the
     actual cardinality of the key (*note SHOW INDEX::). By setting
     this to a low value (100?), you can force MySQL to prefer keys
     instead of table scans.

     This variable was added in MySQL 4.0.14.

`max_sort_length'
     The number of bytes to use when sorting `BLOB' or `TEXT' values.
     Only the first `max_sort_length' bytes of each value are used; the
     rest are ignored.

`max_tmp_tables'
     The maximum number of temporary tables a client can keep open at
     the same time.  (This option doesn't yet do anything.)

`max_user_connections'
     The maximum number of simultaneous connections allowed to any
     given MySQL account.  A value of 0 means "no limit."  This
     variable was added in MySQL 3.23.34.

`max_write_lock_count'
     After this many write locks, allow some read locks to run in
     between.  This variable was added in MySQL 3.23.7.

`myisam_data_pointer_size'
     The default pointer size in bytes, to be used by `CREATE TABLE' for
     `MyISAM' tables when no `MAX_ROWS' option is specified.  This
     variable cannot be less than 2 or larger than 8.  The default
     value is 4.  This variable was added in MySQL 4.1.2.  *Note
     `myisam_data_pointer_size': Full table.

`myisam_max_extra_sort_file_size'
     If the temporary file used for fast `MyISAM' index creation would
     be larger than using the key cache by the amount specified here,
     prefer the key cache method.  This is mainly used to force long
     character keys in large tables to use the slower key cache method
     to create the index.  This variable was added in MySQL 3.23.37.
     *Note*: The value is given in megabytes before 4.0.3 and in bytes
     thereafter.

`myisam_max_sort_file_size'
     The maximum size of the temporary file MySQL is allowed to use
     while re-creating a `MyISAM' index (during `REPAIR TABLE', `ALTER
     TABLE', or `LOAD DATA INFILE').  If the file size would be bigger
     than this value, the index will be created using the key cache
     instead, which is slower.  This variable was added in MySQL
     3.23.37.  *Note*: The value is given in megabytes before 4.0.3 and
     in bytes thereafter.

`myisam_recover_options'
     The value of the `--myisam-recover' option.  This variable was
     added in MySQL 3.23.36.

`myisam_repair_threads'
     If this value is greater than 1, `MyISAM' table indexes are
     created in parallel (each index in its own thread) during the
     `Repair by sorting' process.  The default value is 1.  *Note*:
     Multi-threaded repair is still _alpha_ quality code.  This
     variable was added in MySQL 4.0.13.

`myisam_sort_buffer_size'
     The buffer that is allocated when sorting `MyISAM' indexes during a
     `REPAIR TABLE' or when creating indexes with `CREATE INDEX' or
     `ALTER TABLE'.  This variable was added in MySQL 3.23.16.

`named_pipe'
     On Windows, indicates whether the server supports connections over
     named pipes.  This variable was added in MySQL 3.23.50.

`net_buffer_length'
     The communication buffer is reset to this size between queries.
     This should not normally be changed, but if you have very little
     memory, you can set it to the expected length of SQL statements
     sent by clients.  If statements exceed this length, the buffer is
     automatically enlarged, up to `max_allowed_packet' bytes.

`net_read_timeout'
     The number of seconds to wait for more data from a connection
     before aborting the read.  When the server is reading from the
     client, `net_read_timeout' is the timeout value controlling when
     to abort.  When the server is writing to the client,
     `net_write_timeout' is the timeout value controlling when to abort.
     See also `slave_net_timeout'.  This variable was added in MySQL
     3.23.20.

`net_retry_count'
     If a read on a communication port is interrupted, retry this many
     times before giving up.  This value should be set quite high on
     FreeBSD because internal interrupts are sent to all threads.  This
     variable was added in MySQL 3.23.7.

`net_write_timeout'
     The number of seconds to wait for a block to be written to a
     connection before aborting the write.  See also `net_read_timeout'.
     This variable was added in MySQL 3.23.20.

`new'
     This variable is used in MySQL 4.0 to turn on some 4.1 behaviors.
     This variable was added in MySQL 4.0.12.

`old_passwords'
     Whether the server should use pre-4.1-style passwords for MySQL
     user accounts.  This variable was added in MySQL 4.1.1.

`open_files_limit'
     The number of files that the operating system allows `mysqld' to
     open.  This is the real value allowed by the system and might be
     different from the value you gave `mysqld' as a startup option.
     The value is 0 on systems where MySQL can't change the number of
     open files.  This variable was added in MySQL 3.23.20.

`optimizer_prune_level'
     Controls the heuristics applied during query optimization to prune
     less-promising partial plans from the optimizer search space. A
     value of 0 disables heuristics so that the optimizer performs an
     exhaustive search. A value of 1 causes the optimizer to prune
     plans based on the number of rows retrieved by intermediate plans.
     This variable was added in MySQL 5.0.1.

`optimizer_search_depth'
     The maximum depth of search performed by the query optimizer.
     Values larger than the number of relations in a query result in
     better query plans, but take longer to generate an execution plan
     for a query. Values smaller than the number of relations in a
     query return an execution plan quicker, but the resulting plan may
     be far from being optimal. If set to 0, the system automatically
     picks a reasonable value. If set to the maximum number of tables
     used in a query plus 2, the optimizer switches to the original
     algorithm used before MySQL 5.0.1 that performs an exhaustive
     search.  This variable was added in MySQL 5.0.1.

`pid_file'
     The pathname of the process ID (PID) file. This variable can be set
     with the `--pid-file' option.  This variable was added in MySQL
     3.23.23.

`port'
     The port on which the server listens for TCP/IP connections.  This
     variable can be set with the `--port' option.

`preload_buffer_size'
     The size of the buffer that is allocated when preloading indexes.
     This variable was added in MySQL 4.1.1.

`protocol_version'
     The version of the client/server protocol used by the MySQL server.
     This variable was added in MySQL 3.23.18.

`query_alloc_block_size'
     The allocation size of memory blocks that are allocated for
     objects created during query parsing and execution. If you have
     problems with memory fragmentation, it might help to increase this
     a bit.  This variable was added in MySQL 4.0.16.

`query_cache_limit'
     Don't cache results that are bigger than this. The default value
     is 1MB.  This variable was added in MySQL 4.0.1.

`query_cache_min_res_unit'
     The minimum size for blocks allocated by the query cache.  The
     default value is 4KB. Tuning information for this variable is
     given in *Note Query Cache Configuration::.  This variable is
     present from MySQL 4.1.

`query_cache_size'
     The amount of memory allocated for caching query results.  The
     default value is 0, which disables the query cache.  Note that
     this amount of memory will be allocated even if `query_cache_type'
     is set to 0.  This variable was added in MySQL 4.0.1.

`query_cache_type'
     Set query cache type. Setting the `GLOBAL' value sets the type for
     all clients that connect thereafter. Individual clients can set the
     `SESSION' value to affect their own use of the query cache.

     *Option*   *Description*
     `0' or     Don't cache or retrieve results.  Note that
     `OFF'      this will not deallocate the query cache
                buffer. To do that, you should set
                `query_cache_size' to 0.
     `1' or     Cache all query results except for those that
     `ON'       begin with `SELECT SQL_NO_CACHE'.
     `2' or     Cache results only for queries that begin with
     `DEMAND'   `SELECT SQL_CACHE'.

     This variable was added in MySQL 4.0.3.

`query_cache_wlock_invalidate'
     Normally, when one client acquires a `WRITE' lock on a `MyISAM'
     table, other clients are not blocked from issuing queries for the
     table if the query results are present in the query cache. Setting
     this variable to 1 causes acquisition of a `WRITE' lock for a
     table to invalidate any queries in the query cache that refer to
     the table. This forces other clients that attempt to access the
     table to wait while the lock is in effect.  This variable was
     added in MySQL 4.0.19.

`query_prealloc_size'
     The size of the persistent buffer used for query parsing and
     execution.  This buffer is not freed between queries.  If you are
     running complex queries, a larger `query_prealloc_size' value
     might be helpful in improving performance, because it can reduce
     the need for the server to perform memory allocation during query
     execution operations.  This variable was added in MySQL 4.0.16.

`range_alloc_block_size'
     The size of blocks that are allocated when doing range
     optimization.  This variable was added in MySQL 4.0.16.

`read_buffer_size'
     Each thread that does a sequential scan allocates a buffer of this
     size for each table it scans. If you do many sequential scans, you
     might want to increase this value.  This variable was added in
     MySQL 4.0.3.  Previously, it was named `record_buffer'.

`read_only'
     When the variable is set to `ON' for a replication slave server, it
     causes the slave to allow no updates except from slave threads or
     from users with the `SUPER' privilege.  This can be useful to
     ensure that a slave server accepts no updates from clients.  This
     variable was added in MySQL 4.0.14.

`relay_log_purge'
     Disables or enables automatic purging of relay logs as soon as
     they are not needed any more.  The default value is 1 (enabled).
     This variable was added in MySQL 4.1.1.

`read_rnd_buffer_size'
     When reading rows in sorted order after a sort, the rows are read
     through this buffer to avoid disk seeks.  Setting the variable to
     a large value can improve `ORDER BY' performance by a lot.
     However, this is a buffer allocated for each client, so you should
     not set the global variable to a large value. Instead, change the
     session variable only from within those clients that need to run
     large queries.  This variable was added in MySQL 4.0.3.
     Previously, it was named `record_rnd_buffer'.

`safe_show_database'
     Don't show databases for which the user has no database or table
     privileges. This can improve security if you're concerned about
     people being able to see what databases other users have. See also
     `skip_show_database'.

     This variable was removed in MySQL 4.0.5. Instead, use the `SHOW
     DATABASES' privilege to control access by MySQL accounts to
     database names.

`secure_auth'
     If the MySQL server has been started with the `--secure-auth'
     option, it blocks connections from all accounts that have
     passwords stored in the old (pre-4.1) format. In that case, the
     value of this variable is `ON', otherwise it is `OFF'.

     You should enable this option if you want to prevent all usage of
     passwords in old format (and hence insecure communication over the
     network).  This variable was added in MySQL 4.1.1.

     Server startup will fail with an error if this option is enabled
     and the privilege tables are in pre-4.1 format.

     When used as a client-side option, the client refuses to connect
     to a server if the server requires a password in old format for
     the client account.

`server_id'
     The value of the `--server-id' option. It is used for master and
     slave replication servers.  This variable was added in MySQL
     3.23.26.

`shared_memory'
     Whether or not the server allows shared-memory connections.
     Currently, only Windows servers support this.  This variable was
     added in MySQL 4.1.1.

`shared_memory_base_name'
     Whether or not the server allows shared-memory connections.
     Currently, only Windows servers support this.  This variable was
     added in MySQL 4.1.0.

`skip_external_locking'
     This is `OFF' if `mysqld' uses external locking.  This variable
     was added in MySQL 4.0.3.  Previously, it was named `skip_locking'.

`skip_networking'
     This is `ON' if the server allows only local (non-TCP/IP)
     connections.  On Unix, local connections use a Unix socket file.
     On Windows, local connections use a named pipe.  On NetWare, only
     TCP/IP connections are supported, so do not set this variable to
     `ON'.  This variable was added in MySQL 3.22.23.

`skip_show_database'
     This prevents people from using the `SHOW DATABASES' statement if
     they don't have the `SHOW DATABASES' privilege. This can improve
     security if you're concerned about people being able to see what
     databases other users have. See also `safe_show_database'.  This
     variable was added in MySQL 3.23.4.  As of MySQL 4.0.2, its effect
     also depends on the `SHOW DATABASES' privilege: If the variable
     value is `ON', the `SHOW DATABASES' statement is allowed only to
     users who have the `SHOW DATABASES' privilege, and the statement
     displays all database names.  If the value is `OFF', `SHOW
     DATABASES' is allowed to all users, but displays each database
     name only if the user has the `SHOW DATABASES' privilege or some
     privilege for the database.

`slave_compressed_protocol'
     Whether to use compression of the slave/master protocol if both the
     slave and the master support it.  This variable was added in MySQL
     4.0.3.

`slave_net_timeout'
     The number of seconds to wait for more data from a master/slave
     connection before aborting the read.  This variable was added in
     MySQL 3.23.40.

`slow_launch_time'
     If creating a thread takes longer than this many seconds, the
     server increments the `Slow_launch_threads' status variable.  This
     variable was added in MySQL 3.23.15.

`socket'
     On Unix, this is the Unix socket file used for local client
     connections.  On Windows, this is the name of the named pipe used
     for local client connections.

`sort_buffer_size'
     Each thread that needs to do a sort allocates a buffer of this
     size. Increase this value for faster `ORDER BY' or `GROUP BY'
     operations.  *Note Temporary files::.

`sql_mode'
     The current server SQL mode.  This variable was added in MySQL
     3.23.41.  It can be set dynamically as of MySQL 4.1.1.  *Note
     Server SQL mode::.

`sql_slave_skip_counter'
     The number of events from the master that a slave server should
     skip.  It was added in MySQL 3.23.33.

`storage_engine'
     This variable is a synonym for `table_type'.  It was added in
     MySQL 4.1.2.

`sync_binlog'
     If positive, the MySQL server will synchronize its binary log to
     disk (`fdatasync()') after every `sync_binlog''th write to this
     binary log. Note that there is one write to the binary log per
     statement if in autocommit mode, and otherwise one write per
     transaction. The default value is 0 which does no sync'ing to
     disk. A value of 1 is the safest choice, because in case of crash
     you will lose at most one statement/transaction from the binary
     log; but it is also the slowest choice (unless the disk has a
     battery-backed cache, which makes sync'ing very fast). This
     variable was added in MySQL 4.1.3.

`sync_frm'
     This was added as a command-line option in MySQL 4.0.18, and is
     also a settable global variable since MySQL 4.1.3. If set to 1,
     when a non-temporary table is created it will synchronize its
     `.frm' file to disk (`fdatasync()'); this is slower but safer in
     case of crash. Default is 1.

`system_time_zone'
     The server system time zone. When the server starts, it attempts
     to determine the time zone of the host machine. For example, if
     the `TZ' environment variable is set, its value is used to set
     `system_time_zone'.  This variable was added in MySQL 4.1.3.

`table_cache'
     The number of open tables for all threads. Increasing this value
     increases the number of file descriptors that `mysqld' requires.
     You can check whether you need to increase the table cache by
     checking the `Opened_tables' status variable.  *Note Server status
     variables::.  If the value of `Opened_tables' is large and you
     don't do `FLUSH TABLES' a lot (which just forces all tables to be
     closed and reopened), then you should increase the value of the
     `table_cache' variable.

     For more information about the table cache, see *Note Table
     cache::.

`table_type'
     The default table type (storage engine).  To set the table type at
     server startup, use the `--default-table-type' option.  This
     variable was added in MySQL 3.23.0.  *Note Server options::.

`thread_cache_size'
     How many threads the server should cache for reuse.  When a client
     disconnects, the client's threads are put in the cache if there
     aren't already `thread_cache_size' threads there.  Requests for
     threads are satisfied by reusing threads taken from the cache if
     possible, and only when the cache is empty is a new thread
     created.  This variable can be increased to improve performance if
     you have a lot of new connections. (Normally this doesn't give a
     notable performance improvement if you have a good thread
     implementation.)  By examining the difference between the
     `Connections' and `Threads_created' status variables (*note Server
     status variables:: for details) you can see how efficient the
     thread cache is.  This variable was added in MySQL 3.23.16.

`thread_concurrency'
     On Solaris, `mysqld' calls `thr_setconcurrency()' with this value.
     This function allows applications to give the threads system a
     hint about the desired number of threads that should be run at the
     same time.  This variable was added in MySQL 3.23.7.

`thread_stack'
     The stack size for each thread.  Many of the limits detected by the
     `crash-me' test are dependent on this value. The default is large
     enough for normal operation.  *Note MySQL Benchmarks::.

`time_zone'
     The current time zone. The initial value of this is `'SYSTEM''
     (use the value of `system_time_zone'), but can be specified
     explicitly at server startup time with the `--default-time-zone'
     option.  This variable was added in MySQL 4.1.3.

`timezone'
     The time zone for the server.  This is set from the `TZ'
     environment variable when `mysqld' is started.  The time zone also
     can be set by giving a `--timezone' argument to `mysqld_safe'.
     This variable was added in MySQL 3.23.15. As of MySQL 4.1.3, it is
     obsolete and has been replaced by the `system_time_zone' variable.
     *Note Timezone problems::.

`tmp_table_size'
     If an in-memory temporary table exceeds this size, MySQL
     automatically converts it to an on-disk `MyISAM' table.  Increase
     the value of `tmp_table_size' if you do many advanced `GROUP BY'
     queries and you have lots of memory.

`tmpdir'
     The directory used for temporary files and temporary tables.
     Starting from MySQL 4.1, this variable can be set to a list of
     several paths that are used in round-robin fashion. Paths should
     be separated by colon characters (`:') on Unix and semicolon
     characters (`;') on Windows, NetWare, and OS/2.

     This feature can be used to spread the load between several
     physical disks.  If the MySQL server is acting as a replication
     slave, you should not set `tmpdir' to point to a directory on a
     memory-based filesystem or to a directory that is cleared when the
     server host restarts.  A replication slave needs some of its
     temporary files to survive a machine restart so that it can
     replicate temporary tables or `LOAD DATA INFILE' operations. If
     files in the temporary file directory are lost when the server
     restarts, replication will fail.

     This variable was added in MySQL 3.22.4.

`transaction_alloc_block_size'
     The allocation size of memory blocks that are allocated for
     storing queries that are part of a transaction to be stored in the
     binary log when doing a commit.  This variable was added in MySQL
     4.0.16.

`transaction_prealloc_size'
     The size of the persistent buffer for `transaction_alloc_blocks'
     that is not freed between queries. By making this big enough to
     fit all queries in a common transaction, you can avoid a lot of
     `malloc()' calls.  This variable was added in MySQL 4.0.16.

`tx_isolation'
     The default transaction isolation level.  This variable was added
     in MySQL 4.0.3.

`updatable_views_with_limit'
     This variable controls whether updates can be made using a view
     that does not contain a primary key in the underlying table, if
     the update contains a `LIMIT' clause. (Such updates often are
     generated by GUI tools.)  An update is an `UPDATE' or `DELETE'
     statement.  Primary key here means a `PRIMARY KEY', or a `UNIQUE'
     index in which no column can contain `NULL'.

     The variable can have two values:

        * `1' or `YES': Issue a warning only (not an error message).
          This is the default value.

        * `0' or `NO': Prohibit the update.

     This variable was added in MySQL 5.0.2.

`version'
     The version number for the server.

`version_bdb'
     The `BDB' storage engine version.  This variable was added in
     MySQL 3.23.31 with the name `bdb_version' and renamed to
     `version_bdb' in MySQL 4.1.1.

`version_comment'
     The `configure' script has a `--with-comment' option that allows a
     comment to be specified when building MySQL.  This variable
     contains the value of that comment.  This variable was added in
     MySQL 4.0.17.

`version_compile_machine'
     The type of machine MySQL was built on.  This variable was added
     in MySQL 4.1.1.

`version_compile_os'
     The type of operating system MySQL was built on.  This variable
     was added in MySQL 4.0.19.

`wait_timeout'
     The number of seconds the server waits for activity on a
     non-interactive connection before closing it.

     On thread startup, the session `wait_timeout' value is initialized
     from the global `wait_timeout' value or from the global
     `interactive_timeout' value, depending on the type of client (as
     defined by the `CLIENT_INTERACTIVE' connect option to
     `mysql_real_connect()'). See also `interactive_timeout'.

Dynamic System Variables
........................

Beginning with MySQL 4.0.3, many server system variables are dynamic
and can be set at runtime using `SET GLOBAL' or `SET SESSION'. You can
also select their values using `SELECT'.  *Note System Variables::.

The following table shows the full list of all dynamic system variables.
The last column indicates for each variable whether `GLOBAL' or
`SESSION' (or both) apply.

*Variable Name*                  *Value Type*       *Type*
`autocommit'                     boolean            `SESSION'
`big_tables'                     boolean            `SESSION'
`binlog_cache_size'              numeric            `GLOBAL'
`bulk_insert_buffer_size'        numeric            `GLOBAL' | `SESSION'
`character_set_client'           string             `GLOBAL' | `SESSION'
`character_set_connection'       string             `GLOBAL' | `SESSION'
`character_set_results'          string             `GLOBAL' | `SESSION'
`character_set_server'           string             `GLOBAL' | `SESSION'
`collation_connection'           string             `GLOBAL' | `SESSION'
`collation_server'               string             `GLOBAL' | `SESSION'
`concurrent_insert'              boolean            `GLOBAL'
`connect_timeout'                numeric            `GLOBAL'
`convert_character_set'          string             `GLOBAL' | `SESSION'
`default_week_format'            numeric            `GLOBAL' | `SESSION'
`delay_key_write'                `OFF' | `ON' |     `GLOBAL'
                                 `ALL'
`delayed_insert_limit'           numeric            `GLOBAL'
`delayed_insert_timeout'         numeric            `GLOBAL'
`delayed_queue_size'             numeric            `GLOBAL'
`error_count'                    numeric            `SESSION'
`expire_logs_days'               numeric            `GLOBAL'
`flush'                          boolean            `GLOBAL'
`flush_time'                     numeric            `GLOBAL'
`foreign_key_checks'             boolean            `SESSION'
`ft_boolean_syntax'              numeric            `GLOBAL'
`group_concat_max_len'           numeric            `GLOBAL' | `SESSION'
`identity'                       numeric            `SESSION'
`insert_id'                      boolean            `SESSION'
`interactive_timeout'            numeric            `GLOBAL' | `SESSION'
`join_buffer_size'               numeric            `GLOBAL' | `SESSION'
`key_buffer_size'                numeric            `GLOBAL'
`last_insert_id'                 numeric            `SESSION'
`local_infile'                   boolean            `GLOBAL'
`log_warnings'                   numeric            `GLOBAL'
`long_query_time'                numeric            `GLOBAL' | `SESSION'
`low_priority_updates'           boolean            `GLOBAL' | `SESSION'
`max_allowed_packet'             numeric            `GLOBAL' | `SESSION'
`max_binlog_cache_size'          numeric            `GLOBAL'
`max_binlog_size'                numeric            `GLOBAL'
`max_connect_errors'             numeric            `GLOBAL'
`max_connections'                numeric            `GLOBAL'
`max_delayed_threads'            numeric            `GLOBAL'
`max_error_count'                numeric            `GLOBAL' | `SESSION'
`max_heap_table_size'            numeric            `GLOBAL' | `SESSION'
`max_insert_delayed_threads'     numeric            `GLOBAL'
`max_join_size'                  numeric            `GLOBAL' | `SESSION'
`max_relay_log_size'             numeric            `GLOBAL'
`max_seeks_for_key'              numeric            `GLOBAL' | `SESSION'
`max_sort_length'                numeric            `GLOBAL' | `SESSION'
`max_tmp_tables'                 numeric            `GLOBAL' | `SESSION'
`max_user_connections'           numeric            `GLOBAL'
`max_write_lock_count'           numeric            `GLOBAL'
`myisam_data_pointer_size'       numeric            `GLOBAL'
`myisam_max_extra_sort_file_size'numeric            `GLOBAL' | `SESSION'
`myisam_max_sort_file_size'      numeric            `GLOBAL' | `SESSION'
`myisam_repair_threads'          numeric            `GLOBAL' | `SESSION'
`myisam_sort_buffer_size'        numeric            `GLOBAL' | `SESSION'
`net_buffer_length'              numeric            `GLOBAL' | `SESSION'
`net_read_timeout'               numeric            `GLOBAL' | `SESSION'
`net_retry_count'                numeric            `GLOBAL' | `SESSION'
`net_write_timeout'              numeric            `GLOBAL' | `SESSION'
`old_passwords'                  numeric            `GLOBAL' | `SESSION'
`optimizer_prune_level'          numeric            `GLOBAL' | `SESSION'
`optimizer_search_depth'         numeric            `GLOBAL' | `SESSION'
`preload_buffer_size'            numeric            `GLOBAL' | `SESSION'
`query_alloc_block_size'         numeric            `GLOBAL' | `SESSION'
`query_cache_limit'              numeric            `GLOBAL'
`query_cache_size'               numeric            `GLOBAL'
`query_cache_type'               enumeration        `GLOBAL' | `SESSION'
`query_cache_wlock_invalidate'   boolean            `GLOBAL' | `SESSION'
`query_prealloc_size'            numeric            `GLOBAL' | `SESSION'
`range_alloc_block_size'         numeric            `GLOBAL' | `SESSION'
`read_buffer_size'               numeric            `GLOBAL' | `SESSION'
`read_only'                      numeric            `GLOBAL'
`read_rnd_buffer_size'           numeric            `GLOBAL' | `SESSION'
`rpl_recovery_rank'              numeric            `GLOBAL'
`safe_show_database'             boolean            `GLOBAL'
`secure_auth'                    boolean            `GLOBAL'
`server_id'                      numeric            `GLOBAL'
`slave_compressed_protocol'      boolean            `GLOBAL'
`slave_net_timeout'              numeric            `GLOBAL'
`slow_launch_time'               numeric            `GLOBAL'
`sort_buffer_size'               numeric            `GLOBAL' | `SESSION'
`sql_auto_is_null'               boolean            `SESSION'
`sql_big_selects'                boolean            `SESSION'
`sql_big_tables'                 boolean            `SESSION'
`sql_buffer_result'              boolean            `SESSION'
`sql_log_bin'                    boolean            `SESSION'
`sql_log_off'                    boolean            `SESSION'
`sql_log_update'                 boolean            `SESSION'
`sql_low_priority_updates'       boolean            `GLOBAL' | `SESSION'
`sql_max_join_size'              numeric            `GLOBAL' | `SESSION'
`sql_mode'                       enumeration        `GLOBAL' | `SESSION'
`sql_quote_show_create'          boolean            `SESSION'
`sql_safe_updates'               boolean            `SESSION'
`sql_select_limit'               numeric            `SESSION'
`sql_slave_skip_counter'         numeric            `GLOBAL'
`updatable_views_with_limit'     enumeration        `GLOBAL' | `SESSION'
`sql_warnings'                   boolean            `SESSION'
`sync_binlog'                    numeric            `GLOBAL'
`sync_frm'                       boolean            `GLOBAL'
`storage_engine'                 enumeration        `GLOBAL' | `SESSION'
`table_cache'                    numeric            `GLOBAL'
`table_type'                     enumeration        `GLOBAL' | `SESSION'
`thread_cache_size'              numeric            `GLOBAL'
`time_zone'                      string             `GLOBAL' | `SESSION'
`timestamp'                      boolean            `SESSION'
`tmp_table_size'                 enumeration        `GLOBAL' | `SESSION'
`transaction_alloc_block_size'   numeric            `GLOBAL' | `SESSION'
`transaction_prealloc_size'      numeric            `GLOBAL' | `SESSION'
`tx_isolation'                   enumeration        `GLOBAL' | `SESSION'
`unique_checks'                  boolean            `SESSION'
`wait_timeout'                   numeric            `GLOBAL' | `SESSION'
`warning_count'                  numeric            `SESSION'

Variables that are marked as "string" take a string value.  Variables
that are marked as "numeric" take a numeric value. Variables that are
marked as "boolean" can be set to 0, 1, `ON' or `OFF'. Variables that
are marked as "enumeration" normally should be set to one of the
available values for the variable, but can also be set to the number
that corresponds to the desired enumeration value.  For
enumeration-valued system variables, the first enumeration value
corresponds to 0. This differs from `ENUM' columns, for which the first
enumeration value corresponds to 1.

Server Status Variables
-----------------------

The server maintains many status variables that provide information
about its operations. You can view these variables and their values by
using the `SHOW STATUS' statement:

     mysql> SHOW STATUS;
     +--------------------------+------------+
     | Variable_name            | Value      |
     +--------------------------+------------+
     | Aborted_clients          | 0          |
     | Aborted_connects         | 0          |
     | Bytes_received           | 155372598  |
     | Bytes_sent               | 1176560426 |
     | Connections              | 30023      |
     | Created_tmp_disk_tables  | 0          |
     | Created_tmp_files        | 60         |
     | Created_tmp_tables       | 8340       |
     | Delayed_errors           | 0          |
     | Delayed_insert_threads   | 0          |
     | Delayed_writes           | 0          |
     | Flush_commands           | 1          |
     | Handler_delete           | 462604     |
     | Handler_read_first       | 105881     |
     | Handler_read_key         | 27820558   |
     | Handler_read_next        | 390681754  |
     | Handler_read_prev        | 6022500    |
     | Handler_read_rnd         | 30546748   |
     | Handler_read_rnd_next    | 246216530  |
     | Handler_update           | 16945404   |
     | Handler_write            | 60356676   |
     | Key_blocks_used          | 14955      |
     | Key_read_requests        | 96854827   |
     | Key_reads                | 162040     |
     | Key_write_requests       | 7589728    |
     | Key_writes               | 3813196    |
     | Max_used_connections     | 0          |
     | Not_flushed_delayed_rows | 0          |
     | Not_flushed_key_blocks   | 0          |
     | Open_files               | 2          |
     | Open_streams             | 0          |
     | Open_tables              | 1          |
     | Opened_tables            | 44600      |
     | Qcache_free_blocks       | 36         |
     | Qcache_free_memory       | 138488     |
     | Qcache_hits              | 79570      |
     | Qcache_inserts           | 27087      |
     | Qcache_lowmem_prunes     | 3114       |
     | Qcache_not_cached        | 22989      |
     | Qcache_queries_in_cache  | 415        |
     | Qcache_total_blocks      | 912        |
     | Questions                | 2026873    |
     | Select_full_join         | 0          |
     | Select_full_range_join   | 0          |
     | Select_range             | 99646      |
     | Select_range_check       | 0          |
     | Select_scan              | 30802      |
     | Slave_open_temp_tables   | 0          |
     | Slave_running            | OFF        |
     | Slow_launch_threads      | 0          |
     | Slow_queries             | 0          |
     | Sort_merge_passes        | 30         |
     | Sort_range               | 500        |
     | Sort_rows                | 30296250   |
     | Sort_scan                | 4650       |
     | Table_locks_immediate    | 1920382    |
     | Table_locks_waited       | 0          |
     | Threads_cached           | 0          |
     | Threads_connected        | 1          |
     | Threads_created          | 30022      |
     | Threads_running          | 1          |
     | Uptime                   | 80380      |
     +--------------------------+------------+

Many status variables are reset to 0 by the `FLUSH STATUS' statement.

The status variables have the following meanings.  The `Com_XXX'
statement counter variables were added beginning with MySQL 3.23.47. The
`Qcache_XXX' query cache variables were added beginning with MySQL
4.0.1. Otherwise, variables with no version indicated have been present
since at least MySQL 3.22.

`Aborted_clients'
     The number of connections that were aborted because the client
     died without closing the connection properly.  *Note Communication
     errors::.

`Aborted_connects'
     The number of tries to connect to the MySQL server that failed.
     *Note Communication errors::.

`Binlog_cache_disk_use'
     The number of transactions that used the temporary binary log
     cache but that exceeded the value of `binlog_cache_size' and used
     a temporary file to store statements from the transaction.  This
     variable was added in MySQL 4.1.2.

`Binlog_cache_use'
     The number of transactions that used the temporary binary log
     cache.  This variable was added in MySQL 4.1.2.

`Bytes_received'
     The number of bytes received from all clients.  This variable was
     added in MySQL 3.23.7.

`Bytes_sent'
     The number of bytes sent to all clients.  This variable was added
     in MySQL 3.23.7.

`Com_XXX'
     The number of times each XXX statement has been executed.  There
     is one status variable for each type of statement. For example,
     `Com_delete' and `Com_insert' count `DELETE' and `INSERT'
     statements.

`Connections'
     The number of connection attempts (successful or not) to the MySQL
     server.

`Created_tmp_disk_tables'
     The number of temporary tables on disk created automatically by
     the server while executing statements.  This variable was added in
     MySQL 3.23.24.

`Created_tmp_files'
     How many temporary files `mysqld' has created.  This variable was
     added in MySQL 3.23.28.

`Created_tmp_tables'
     The number of in-memory temporary tables created automatically by
     the server while executing statements.  If
     `Created_tmp_disk_tables' is big, you may want to increase the
     `tmp_table_size' value to cause temporary tables to be memory-based
     instead of disk-based.

`Delayed_errors'
     The number of rows written with `INSERT DELAYED' for which some
     error occurred (probably `duplicate key').

`Delayed_insert_threads'
     The number of `INSERT DELAYED' handler threads in use.

`Delayed_writes'
     The number of `INSERT DELAYED' rows written.

`Flush_commands'
     The number of executed `FLUSH' statements.

`Handler_commit'
     The number of internal `COMMIT' statements.  This variable was
     added in MySQL 4.0.2.

`Handler_discover'
     The MySQL server can ask the `NDB Cluster' storage engine if it
     knows about a table with a given name. This is called discovery.
     `Handler_discover' indicates the number of time tables have been
     discovered.  This variable was added in MySQL 4.1.2.

`Handler_delete'
     The number of times a row was deleted from a table.

`Handler_read_first'
     The number of times the first entry was read from an index.  If
     this is high, it suggests that the server is doing a lot of full
     index scans; for example, `SELECT col1 FROM foo', assuming that
     `col1' is indexed.

`Handler_read_key'
     The number of requests to read a row based on a key. If this is
     high, it is a good indication that your queries and tables are
     properly indexed.

`Handler_read_next'
     The number of requests to read the next row in key order. This
     will be incremented if you are querying an index column with a
     range constraint or if you are doing an index scan.

`Handler_read_prev'
     The number of requests to read the previous row in key order.
     This read method is mainly used to optimize `ORDER BY ... DESC'.
     This variable was added in MySQL 3.23.6.

`Handler_read_rnd'
     The number of requests to read a row based on a fixed position.
     This will be high if you are doing a lot of queries that require
     sorting of the result.  You probably have a lot of queries that
     require MySQL to scan whole tables or you have joins that don't
     use keys properly.

`Handler_read_rnd_next'
     The number of requests to read the next row in the data file.
     This will be high if you are doing a lot of table scans. Generally
     this suggests that your tables are not properly indexed or that
     your queries are not written to take advantage of the indexes you
     have.

`Handler_rollback'
     The number of internal `ROLLBACK' statements.  This variable was
     added in MySQL 4.0.2.

`Handler_update'
     The number of requests to update a row in a table.

`Handler_write'
     The number of requests to insert a row in a table.

`Key_blocks_not_flushed'
     The number of key blocks in the key cache that have changed but
     haven't yet been flushed to disk.  This variable was added in
     MySQL 4.1.1.  It used to be known as `Not_flushed_key_blocks'.

`Key_blocks_unused'
     This variable was added in MySQL 4.1.2.  *Note Server system
     variables::.

`Key_blocks_used'
     The number of used blocks in the key cache.  You can use this
     value to determine how much of the key cache is in use; see the
     discussion of `key_buffer_size' in *Note Server system variables::.

`Key_read_requests'
     The number of requests to read a key block from the cache.

`Key_reads'
     The number of physical reads of a key block from disk.  If
     `Key_reads' is big, then your `key_buffer_size' value is probably
     too small.  The cache miss rate can be calculated as
     `Key_reads'/`Key_read_requests'.

`Key_write_requests'
     The number of requests to write a key block to the cache.

`Key_writes'
     The number of physical writes of a key block to disk.

`Last_query_cost'
     The total cost of the last compiled query as computed by the query
     optimizer. Useful for comparing the cost of different query plans
     for the same query. The default value of -1 means that no query
     has been compiled yet. This variable was added in MySQL 5.0.1.

`Max_used_connections'
     The maximum number of connections that have been in use
     simultaneously since the server started.

`Not_flushed_delayed_rows'
     The number of rows waiting to be written in `INSERT DELAY' queues.

`Not_flushed_key_blocks'
     The old name for `Key_blocks_not_flushed' before MySQL 4.1.1.

`Open_files'
     The number of files that are open.

`Open_streams'
     The number of streams that are open (used mainly for logging).

`Open_tables'
     The number of tables that are open.

`Opened_tables'
     The number of tables that have been opened.  If `Opened_tables' is
     big, your `table_cache' value is probably too small.

`Qcache_free_blocks'
     The number of free memory blocks in query cache.

`Qcache_free_memory'
     The amount of free memory for query cache.

`Qcache_hits'
     The number of cache hits.

`Qcache_inserts'
     The number of queries added to the cache.

`Qcache_lowmem_prunes'
     The number of queries that were deleted from the cache because of
     low memory.

`Qcache_not_cached'
     The number of non-cached queries (not cachable, or due to
     `query_cache_type').

`Qcache_queries_in_cache'
     The number of queries registered in the cache.

`Qcache_total_blocks'
     The total number of blocks in the query cache.

`Questions'
     The number of queries that have been sent to the server.

`Rpl_status'
     The status of failsafe replication (not yet implemented).

`Select_full_join'
     The number of joins that do not use indexes.  If this value is not
     0, you should carefully check the indexes of your tables.  This
     variable was added in MySQL 3.23.25.

`Select_full_range_join'
     The number of joins that used a range search on a reference table.
     This variable was added in MySQL 3.23.25.

`Select_range'
     The number of joins that used ranges on the first table. (It's
     normally not critical even if this is big.)  This variable was
     added in MySQL 3.23.25.

`Select_range_check'
     The number of joins without keys that check for key usage after
     each row.  (If this is not 0, you should carefully check the
     indexes of your tables.)  This variable was added in MySQL 3.23.25.

`Select_scan'
     The number of joins that did a full scan of the first table.  This
     variable was added in MySQL 3.23.25.

`Slave_open_temp_tables'
     The number of temporary tables currently open by the slave SQL
     thread.  This variable was added in MySQL 3.23.29.

`Slave_running'
     This is `ON' if this server is a slave that is connected to a
     master.  This variable was added in MySQL 3.23.16.

`Slow_launch_threads'
     The number of threads that have taken more than `slow_launch_time'
     seconds to create.  This variable was added in MySQL 3.23.15.

`Slow_queries'
     The number of queries that have taken more than `long_query_time'
     seconds. *Note Slow query log::.

`Sort_merge_passes'
     The number of merge passes the sort algorithm has had to do. If
     this value is large, you should consider increasing the value of
     the `sort_buffer_size' system variable.  This variable was added
     in MySQL 3.23.28.

`Sort_range'
     The number of sorts that were done with ranges.  This variable was
     added in MySQL 3.23.25.

`Sort_rows'
     The number of sorted rows.  This variable was added in MySQL
     3.23.25.

`Sort_scan'
     The number of sorts that were done by scanning the table.  This
     variable was added in MySQL 3.23.25.

`Ssl_XXX'
     Variables used for SSL connections.  These variables were added in
     MySQL 4.0.0.

`Table_locks_immediate'
     The number of times that a table lock was acquired immediately.
     This variable was added as of MySQL 3.23.33.

`Table_locks_waited'
     The number of times that a table lock could not be acquired
     immediately and a wait was needed. If this is high, and you have
     performance problems, you should first optimize your queries, and
     then either split your table or tables or use replication.  This
     variable was added as of MySQL 3.23.33.

`Threads_cached'
     The number of threads in the thread cache.  This variable was
     added in MySQL 3.23.17.

`Threads_connected'
     The number of currently open connections.

`Threads_created'
     The number of threads created to handle connections.  If
     `Threads_created' is big, you may want to increase the
     `thread_cache_size' value.  The cache hit rate can be calculated
     as `Threads_created'/`Connections'.  This variable was added in
     MySQL 3.23.31.

`Threads_running'
     The number of threads that are not sleeping.

`Uptime'
     The number of seconds the server has been up.

The MySQL Server Shutdown Process
=================================

The server shutdown process can be summarized like this:

  1. The shutdown process is initiated

  2. The server creates a shutdown thread if necessary

  3. The server stops accepting new connections

  4. The server terminates current activity

  5. Storage engines are shut down or closed

  6. The server exits

A more detailed description of the process follows:

  1. The shutdown process is initiated

     Server shutdown can be initiated several ways. For example, a user
     with the `SHUTDOWN' privilege can execute a `mysqladmin shutdown'
     command. `mysqladmin' can be used on any platform supported by
     MySQL. Other operating sytem-specific shutdown initiation methods
     are possible as well: The server shuts down on Unix when it
     receives a `SIGTERM' signal. A server running as a service on
     Windows shuts down when the services manager tells it to.

  2. The server creates a shutdown thread if necessary

     Depending on how shutdown was initiated, the server might create a
     thread to handle the shutdown process.  If shutdown was requested
     by a client, a shutdown thread is created.  If shutdown is the
     result of receiving a `SIGTERM' signal, the signal thread might
     handle shutdown itself, or it might create a separate thread to do
     so.  If the server tries to create a shutdown thread and cannot
     (for example, if memory is exhausted), it issues a diagnostic
     message that will appear in the error log:

          Error: Can't create thread to kill server

  3. The server stops accepting new connections

     To prevent new activity from being initiated during shutdown, the
     server stops accepting new client connections. It does this by
     closing the network connections to which it normally listens for
     connections: the TCP/IP port, the Unix socket file, the Windows
     named pipe.

  4. The server terminates current activity

     For each thread that is associated with a client connection, the
     connection to the client is broken and the thread is marked as
     killed. Threads die when they notice that they are so marked.
     Threads for idle connections die quickly. Threads that currently
     are processing queries check their state periodically and take
     longer to die.  For additional information about thread
     termination, see *Note `KILL': KILL, in particular for the
     instructions about killed `REPAIR TABLE' or `OPTIMIZE TABLE'
     operations on `MyISAM' tables.

     For threads that have an open transaction, the tranaction is
     rolled back.  Note that if a thread is updating a
     non-transactional table, an operation such as a multiple-row
     `UPDATE' or `INSERT' may leave the table partially updated,
     because the operation can terminate before completion.

     If the server is a master replication server, threads associated
     with currently connected slaves are treated like other client
     threads. That is, each one is marked as killed and exits when it
     next checks its state.

     If the server is a slave replication server, the I/O and SQL
     threads, if active, are stopped before client threads are marked
     as killed. The SQL thread is allowed to finish its current
     statement (to avoid causing replication problems) then stops. If
     the SQL thread was in the middle of a transaction at this point,
     the transaction is rolled back.

  5. Storage engines are shut down or closed

     At this stage, the table cache is flushed and all open tables are
     closed.

     Each storage engine performs any actions necessary for tables that
     it manages.  For example, MyISAM flushes any pending index writes
     for a table.  InnoDB flushes its buffer pool to disk, writes the
     current LSN to the tablespace, and terminates its own internal
     threads.

  6. The server exits


General Security Issues
=======================

This section describes some general security issues to be aware of and
what you can do to make your MySQL installation more secure against
attack or misuse. For information specifically about the access control
system that MySQL uses for setting up user accounts and checking
database access, see *Note Privilege system::.

General Security Guidelines
---------------------------

Anyone using MySQL on a computer connected to the Internet should read
this section to avoid the most common security mistakes.

In discussing security, we emphasize the necessity of fully protecting
the entire server host (not just the MySQL server) against all types of
applicable attacks: eavesdropping, altering, playback, and denial of
service. We do not cover all aspects of availability and fault tolerance
here.

MySQL uses security based on Access Control Lists (ACLs) for all
connections, queries, and other operations that users can attempt to
perform. There is also some support for SSL-encrypted connections
between MySQL clients and servers. Many of the concepts discussed here
are not specific to MySQL at all; the same general ideas apply to
almost all applications.

When running MySQL, follow these guidelines whenever possible:

   * *Do not ever give anyone (except MySQL `root' accounts) access to
     the `user' table in the `mysql' database!*  This is critical.
     *The encrypted password is the real password in MySQL.* Anyone who
     knows the password that is listed in the `user' table and has
     access to the host listed for the account *can easily log in as
     that user*.

   * Learn the MySQL access privilege system. The `GRANT' and `REVOKE'
     statements are used for controlling access to MySQL. Do not grant
     any more privileges than necessary. Never grant privileges to all
     hosts.

     Checklist:
        - Try `mysql -u root'. If you are able to connect successfully
          to the server without being asked for a password, you have
          problems. Anyone can connect to your MySQL server as the MySQL
          `root' user with full privileges!  Review the MySQL
          installation instructions, paying particular attention to the
          information about setting a `root' password.  *Note Default
          privileges::.

        - Use the `SHOW GRANTS' statement and check to see who has
          access to what.  Then use the `REVOKE' statement to remove
          those privileges that are not necessary.

   * Do not store any plain-text passwords in your database. If your
     computer becomes compromised, the intruder can take the full list
     of passwords and use them. Instead, use `MD5()', `SHA1()', or some
     other one-way hashing function.

   * Do not choose passwords from dictionaries. There are special
     programs to break them. Even passwords like "xfish98" are very
     bad.  Much better is "duag98" which contains the same word "fish"
     but typed one key to the left on a standard QWERTY keyboard.
     Another method is to use "Mhall" which is taken from the first
     characters of each word in the sentence "Mary had a little lamb."
     This is easy to remember and type, but difficult to guess for
     someone who does not know it.

   * Invest in a firewall. This protects you from at least 50% of all
     types of exploits in any software. Put MySQL behind the firewall
     or in a demilitarized zone (DMZ).

     Checklist:
        - Try to scan your ports from the Internet using a tool such as
          `nmap'. MySQL uses port 3306 by default. This port should not
          be accessible from untrusted hosts. Another simple way to
          check whether or not your MySQL port is open is to try the
          following command from some remote machine, where
          `server_host' is the host on which your MySQL server runs:

               shell> telnet server_host 3306

          If you get a connection and some garbage characters, the port
          is open, and should be closed on your firewall or router,
          unless you really have a good reason to keep it open. If
          `telnet' just hangs or the connection is refused, everything
          is OK; the port is blocked.

   * Do not trust any data entered by users of your applications. They
     can try to trick your code by entering special or escaped
     character sequences in Web forms, URLs, or whatever application
     you have built. Be sure that your application remains secure if a
     user enters something like "`; DROP DATABASE mysql;'". This is an
     extreme example, but large security leaks and data loss might
     occur as a result of hackers using similar techniques, if you do
     not prepare for them.

     A common mistake is to protect only string data values.  Remember
     to check numeric data as well.  If an application generates a
     query such as `SELECT * FROM table WHERE ID=234' when a user
     enters the value `234', the user can enter the value `234 OR 1=1'
     to cause the application to generate the query `SELECT * FROM
     table WHERE ID=234 OR 1=1'.  As a result, the server retrieves
     every record in the table.  This exposes every record and causes
     excessive server load.  The simplest way to protect from this type
     of attack is to use apostrophes around the numeric constants:
     `SELECT * FROM table WHERE ID='234''. If the user enters extra
     information, it all becomes part of the string. In numeric context,
     MySQL automatically converts this string to a number and strips
     any trailing non-numeric characters from it.

     Sometimes people think that if a database contains only publicly
     available data, it need not be protected. This is incorrect.  Even
     if it is allowable to display any record in the database, you
     should still protect against denial of service attacks (for
     example, those that are based on the technique in the preceding
     paragraph that causes the server to waste resources). Otherwise,
     your server becomes unresponsive to legitimate users.

     Checklist:
        - Try to enter `'' and `"' in all your Web forms. If you get
          any kind of MySQL error, investigate the problem right away.

        - Try to modify any dynamic URLs by adding `%22' (`"'), `%23'
          (`#'), and `%27' (`'') in the URL.

        - Try to modify data types in dynamic URLs from numeric ones to
          character ones containing characters from previous examples.
          Your application should be safe against this and similar
          attacks.

        - Try to enter characters, spaces, and special symbols rather
          than numbers in numeric fields. Your application should
          remove them before passing them to MySQL or else generate an
          error. Passing unchecked values to MySQL is very dangerous!

        - Check data sizes before passing them to MySQL.

        - Consider having your application connect to the database
          using a different username than the one you use for
          administrative purposes. Do not give your applications any
          access privileges they do not need.

   * Many application programming interfaces provide a means of
     escaping special characters in data values. Properly used, this
     prevents application users from entering values that cause the
     application to generate statements that have a different effect
     than you intend:
        - MySQL C API: Use the `mysql_real_escape_string()' API call.

        - MySQL++: Use the `escape' and `quote' modifiers for query
          streams.

        - PHP: Use the `mysql_escape_string()' function, which is based
          on the function of the same name in the MySQL C API.  Prior
          to PHP 4.0.3, use  `addslashes()' instead.

        - Perl DBI: Use the `quote()' method or use placeholders.

        - Java JDBC: Use a `PreparedStatement' object and placeholders.

     Other programming interfaces might have similar capabilities.

   * Do not transmit plain (unencrypted) data over the Internet. This
     information is accessible to everyone who has the time and ability
     to intercept it and use it for their own purposes. Instead, use an
     encrypted protocol such as SSL or SSH. MySQL supports internal SSL
     connections as of Version 4.0.0.  SSH port-forwarding can be used
     to create an encrypted (and compressed) tunnel for the
     communication.

   * Learn to use the `tcpdump' and `strings' utilities. For most cases,
     you can check whether MySQL data streams are unencrypted by
     issuing a command like the following:

          shell> tcpdump -l -i eth0 -w - src or dst port 3306 | strings

     (This works under Linux and should work with small modifications
     under other systems.)  Warning: If you do not see plaintext data,
     this doesn't always mean that the information actually is
     encrypted. If you need high security, you should consult with a
     security expert.

Making MySQL Secure Against Attackers
-------------------------------------

When you connect to a MySQL server, you should use a password.  The
password is not transmitted in clear text over the connection. Password
handling during the client connection sequence was upgraded in MySQL
4.1.1 to be very secure.  If you are using an older version of MySQL,
or are still using pre-4.1.1-style passwords, the encryption algorithm
is less strong and with some effort a clever attacker who can sniff the
traffic between the client and the server can crack the password.  (See
*Note Password hashing:: for a discussion of the different password
handling methods.)  If the connection between the client and the server
goes through an untrusted network, you should use an SSH tunnel to
encrypt the communication.

All other information is transferred as text that can be read by anyone
who is able to watch the connection.  If you are concerned about this,
you can use the compressed protocol (in MySQL 3.22 and above) to make
traffic much more difficult to decipher.  To make the connection even
more secure, you should use SSH to get an encrypted TCP/IP connection
between a MySQL server and a MySQL client.  You can find an Open Source
SSH client at `http://www.openssh.org/', and a commercial SSH client at
`http://www.ssh.com/'.

If you are using MySQL 4.0 or newer, you can also use internal OpenSSL
support.  *Note Secure connections::.

To make a MySQL system secure, you should strongly consider the
following suggestions:

   * Use passwords for all MySQL users. A client program does not
     necessarily know the identity of the person running it. It is
     common for client/server applications that the user can specify
     any username to the client program.  For example, anyone can use
     the `mysql' program to connect as any other person simply by
     invoking it as `mysql -u OTHER_USER DB_NAME' if OTHER_USER has no
     password. If all users have a password, connecting using another
     user's account becomes much more difficult.

     To change the password for a user, use the `SET PASSWORD'
     statement.  It is also possible to update the `user' table in the
     `mysql' database directly.  For example, to change the password of
     all MySQL accounts that have a username of `root', do this:

          shell> mysql -u root
          mysql> UPDATE mysql.user SET Password=PASSWORD('NEWPWD')
              -> WHERE User='root';
          mysql> FLUSH PRIVILEGES;

   * Don't run the MySQL server as the Unix `root' user.  This is very
     dangerous, because any user with the `FILE' privilege will be able
     to create files as `root' (for example, `~root/.bashrc'). To
     prevent this, `mysqld' refuses to run as `root' unless that is
     specified explicitly using a `--user=root' option.

     `mysqld' can be run as an ordinary unprivileged user instead.  You
     can also create a separate Unix account named `mysql' to make
     everything even more secure. Use the account only for
     administering MySQL.  To start `mysqld' as another Unix user, add
     a `user' option that specifies the username to the `[mysqld]'
     group of the `/etc/my.cnf' option file or the `my.cnf' option file
     in the server's data directory. For example:

          [mysqld]
          user=mysql

     This causes the server to start as the designated user whether you
     start it manually or by using `mysqld_safe' or `mysql.server'.
     For more details, see *Note Changing MySQL user::.

     Running `mysqld' as a Unix user other than `root' does not mean
     that you need to change the `root' username in the `user' table.
     Usernames for MySQL accounts have nothing to do with usernames for
     Unix accounts.

   * Don't allow the use of symlinks to tables. (This can be disabled
     with the `--skip-symbolic-links' option.) This is especially
     important if you run `mysqld' as `root', because anyone that has
     write access to the server's data directory then could delete any
     file in the system!  *Note Symbolic links to tables::.

   * Make sure that the only Unix user with read or write privileges in
     the database directories is the user that `mysqld' runs as.

   * Don't grant the `PROCESS' or `SUPER' privilege to
     non-administrative users.  The output of `mysqladmin processlist'
     shows the text of the currently executing queries, so any user who
     is allowed to execute that command might be able to see if another
     user issues an `UPDATE user SET password=PASSWORD('not_secure')'
     query.

     `mysqld' reserves an extra connection for users who have the
     `SUPER' privilege (`PROCESS' before MySQL 4.0.2), so that a MySQL
     `root' user can log in and check server activity even if all normal
     connections are in use.

     The `SUPER' privilege can be used to terminate client connections,
     change server operation by changing the value of system variables,
     and control replication servers.

   * Don't grant the `FILE' privilege to non-administrative users.  Any
     user that has this privilege can write a file anywhere in the
     filesystem with the privileges of the `mysqld' daemon!  To make
     this a bit safer, files generated with `SELECT ... INTO OUTFILE'
     will not overwrite existing files and are writable by everyone.

     The `FILE' privilege may also be used to read any file that is
     world-readable or accessible to the Unix user that the server runs
     as.  With this privilege, you can read any file into a database
     table.  This could be abused, for example, by using `LOAD DATA' to
     load `/etc/passwd' into a table, which then can be displayed with
     `SELECT'.

   * If you don't trust your DNS, you should use IP numbers rather than
     hostnames in the grant tables. In any case, you should be very
     careful about creating grant table entries using hostname values
     that contain wildcards!

   * If you want to restrict the number of connections allowed to a
     single account, you can do so by setting the
     `max_user_connections' variable in `mysqld'.  The `GRANT'
     statement also supports resource control options for limiting the
     extent of server use allowed to an account.

Startup Options for `mysqld' Concerning Security
------------------------------------------------

The following `mysqld' options affect security:

`--local-infile[={0|1}]'
     If you start the server with `--local-infile=0', clients cannot use
     `LOCAL' in `LOAD DATA' statements.  *Note `LOAD DATA LOCAL': LOAD
     DATA LOCAL.

`--safe-show-database'
     With this option, the `SHOW DATABASES' statement displays the names
     of only those databases for which the user has some kind of
     privilege.  As of MySQL 4.0.2, this option is deprecated and
     doesn't do anything (it is enabled by default), because there is
     now a `SHOW DATABASES' privilege that can be used to control
     access to database names on a per-account basis. *Note `GRANT':
     GRANT.

`--safe-user-create'
     If this is enabled, a user cannot create new users with the `GRANT'
     statement unless the user has the `INSERT' privilege for the
     `mysql.user' table.  If you want a user to have the ability to
     create new users with those privileges that the user has right to
     grant, you should grant the user the following privilege:

          mysql> GRANT INSERT(user) ON mysql.user TO 'USER_NAME'@'HOST_NAME';

     This will ensure that the user can't change any privilege columns
     directly, but has to use the `GRANT' statement to give privileges
     to other users.

`--secure-auth'
     Disallow authentication for accounts that have old (pre-4.1)
     passwords.  This option is available as of MySQL 4.1.1.

`--skip-grant-tables'
     This option causes the server not to use the privilege system at
     all. This gives everyone _full access_ to all databases!  (You can
     tell a running server to start using the grant tables again by
     executing a `mysqladmin flush-privileges' or `mysqladmin reload'
     command, or by issuing a `FLUSH PRIVILEGES' statement.)

`--skip-name-resolve'
     Hostnames are not resolved.  All `Host' column values in the grant
     tables must be IP numbers or `localhost'.

`--skip-networking'
     Don't allow TCP/IP connections over the network.  All connections
     to `mysqld' must be made via Unix socket files.  This option is
     unsuitable when using a MySQL version prior to 3.23.27 with the
     MIT-pthreads package, because Unix socket files were not supported
     by MIT-pthreads at that time.

`--skip-show-database'
     With this option, the `SHOW DATABASES' statement is allowed only to
     users who have the `SHOW DATABASES' privilege, and the statement
     displays all database names.  Without this option, `SHOW
     DATABASES' is allowed to all users, but displays each database
     name only if the user has the `SHOW DATABASES' privilege or some
     privilege for the database.

Security Issues with `LOAD DATA LOCAL'
--------------------------------------

The `LOAD DATA' statement can load a file that is located on the server
host, or it can load a file that is located on the client host when the
`LOCAL' keyword is specified.

There are two potential security issues with supporting the `LOCAL'
version of `LOAD DATA' statements:

   * The transfer of the file from the client host to the server host
     is initiated by the MySQL server. In theory, a patched server
     could be built that would tell the client program to transfer a
     file of the server's choosing rather than the file named by the
     client in the `LOAD DATA' statement. Such a server could access
     any file on the client host to which the client user has read
     access.

   * In a Web environment where the clients are connecting from a Web
     server, a user could use `LOAD DATA LOCAL' to read any files that
     the Web server process has read access to (assuming that a user
     could run any command against the SQL server). In this
     environment, the client with respect to the MySQL server actually
     is the Web server, not the program being run by the user
     connecting to the Web server.


To deal with these problems, we changed how `LOAD DATA LOCAL' is
handled as of MySQL 3.23.49 and MySQL 4.0.2 (4.0.13 on Windows):

   * By default, all MySQL clients and libraries in binary
     distributions are compiled with the `--enable-local-infile'
     option, to be compatible with MySQL 3.23.48 and before.

   * If you build MySQL from source but don't use the
     `--enable-local-infile' option to `configure', `LOAD DATA LOCAL'
     cannot be used by any client unless it is written explicitly to
     invoke `mysql_options(... MYSQL_OPT_LOCAL_INFILE, 0)'.  *Note
     `mysql_options()': mysql_options.

   * You can disable all `LOAD DATA LOCAL' commands from the server side
     by starting `mysqld' with the `--local-infile=0' option.

   * For the `mysql' command-line client, `LOAD DATA LOCAL' can be
     enabled by specifying the `--local-infile[=1]' option, or disabled
     with the `--local-infile=0' option.  Similarly, for `mysqlimport',
     the `--local' or `-L' option enables local data file loading. In
     any case, successful use of a local loading operation requires
     that the server is enabled to allow it.

   * If you use `LOAD DATA LOCAL' in Perl scripts or other programs that
     read the `[client]' group from option files, you can add the
     `local-infile=1' option to that group. However, to keep this from
     causing problems for programs that do not understand
     `local-infile', specify it using the `loose-' prefix:

          [client]
          loose-local-infile=1

     The `loose-' prefix can be used as of MySQL 4.0.2.

   * If `LOAD DATA LOCAL INFILE' is disabled, either in the server or
     the client, a client that attempts to issue such a statement
     receives the following error message:

          ERROR 1148: The used command is not allowed with this MySQL version


The MySQL Access Privilege System
=================================

MySQL has an advanced but non-standard security/privilege system.  This
section describes how it works.

What the Privilege System Does
------------------------------

The primary function of the MySQL privilege system is to authenticate a
user connecting from a given host, and to associate that user with
privileges on a database such as `SELECT', `INSERT', `UPDATE', and
`DELETE'.

Additional functionality includes the ability to have an anonymous user
and to grant privileges for MySQL-specific functions such as `LOAD DATA
INFILE' and administrative operations.

How the Privilege System Works
------------------------------

The MySQL privilege system ensures that all users may perform only the
operations allowed to them.  As a user, when you connect to a MySQL
server, your identity is determined by _the host from which you
connect_ and _the username you specify_.  The system grants privileges
according to your identity and _what you want to do_.

MySQL considers both your hostname and username in identifying you
because there is little reason to assume that a given username belongs
to the same person everywhere on the Internet.  For example, the user
`joe' who connects from `office.com' need not be the same person as the
user `joe' who connects from `elsewhere.com'.  MySQL handles this by
allowing you to distinguish users on different hosts that happen to
have the same name:  You can grant `joe' one set of privileges for
connections from `office.com', and a different set of privileges for
connections from `elsewhere.com'.

MySQL access control involves two stages:

   * Stage 1: The server checks whether you are even allowed to connect.

   * Stage 2: Assuming that you can connect, the server checks each
     statement you issue to see whether you have sufficient privileges
     to perform it.  For example, if you try to select rows from a
     table in a database or drop a table from the database, the server
     verifies that you have the `SELECT' privilege for the table or the
     `DROP' privilege for the database.

If your privileges are changed (either by yourself or someone else)
while you are connected, those changes will not necessarily take effect
immediately for the next statement you issue.  See *Note Privilege
changes:: for details.

The server stores privilege information in the grant tables of the
`mysql' database (that is, in the database named `mysql').  The MySQL
server reads the contents of these tables into memory when it starts
and re-reads them under the circumstances indicated in *Note Privilege
changes::. Access-control decisions are based on the in-memory copies
of the grant tables.

Normally, you manipulate the contents of the grant tables indirectly by
using the `GRANT' and `REVOKE' statements to set up accounts and control
the privileges available to each one.  *Note `GRANT': GRANT.  The
discussion here describes the underlying structure of the grant tables
and how the server uses their contents when interacting with clients.

The server uses the `user', `db', and `host' tables in the `mysql'
database at both stages of access control.  The columns in these grant
tables are shown here:

*Table Name*   *user*         *db*           *host*
*Scope         `Host'         `Host'         `Host'
columns*
               `User'         `Db'           `Db'
               `Password'     `User'
*Privilege     `Select_priv'  `Select_priv'  `Select_priv'
columns*
               `Insert_priv'  `Insert_priv'  `Insert_priv'
               `Update_priv'  `Update_priv'  `Update_priv'
               `Delete_priv'  `Delete_priv'  `Delete_priv'
               `Index_priv'   `Index_priv'   `Index_priv'
               `Alter_priv'   `Alter_priv'   `Alter_priv'
               `Create_priv'  `Create_priv'  `Create_priv'
               `Drop_priv'    `Drop_priv'    `Drop_priv'
               `Grant_priv'   `Grant_priv'   `Grant_priv'
               `Create_view_priv'`Create_view_priv'`Create_view_priv'
               `Show_view_priv'`Show_view_priv'`Show_view_priv'
               `References_priv'`References_priv'`References_priv'
               `Reload_priv'
               `Shutdown_priv'
               `Process_priv'
               `File_priv'
               `Show_db_priv'
               `Super_priv'
               `Create_tmp_table_priv'`Create_tmp_table_priv'`Create_tmp_table_priv'
               `Lock_tables_priv'`Lock_tables_priv'`Lock_tables_priv'
               `Execute_priv'
               `Repl_slave_priv'
               `Repl_client_priv'
               `ssl_type'
               `ssl_cipher'
               `x509_issuer'
               `x509_subject'
               `max_questions'
               `max_updates'
               `max_connections'

The `ssl_type', `ssl_cipher', `x509_issuer', and `x509_subject' columns
were added in MySQL 4.0.0.

The `Create_tmp_table_priv', `Execute_priv', `Lock_tables_priv',
`Repl_client_priv', `Repl_slave_priv', `Show_db_priv', `Super_priv',
`max_questions', `max_updates', and `max_connections' columns were
added in MySQL 4.0.2.

The `Create_view_priv' and `Show_view_priv' columns were added in MySQL
5.0.1.

During the second stage of access control (request verification), the
server may, if the request involves tables, additionally consult the
`tables_priv' and `columns_priv' tables that provide finer control at
the table and column levels.  The columns in these tables are shown
here:

*Table Name*   *tables_priv*  *columns_priv*
*Scope         `Host'         `Host'
columns*
               `Db'           `Db'
               `User'         `User'
               `Table_name'   `Table_name'
                              `Column_name'
*Privilege     `Table_priv'   `Column_priv'
columns*
               `Column_priv'
*Other         `Timestamp'    `Timestamp'
columns*
               `Grantor'

The `Timestamp' and `Grantor' columns currently are unused and are
discussed no further here.

Each grant table contains scope columns and privilege columns:

   * Scope columns determine the scope of each entry (row) in the
     tables; that is, the context in which the entry applies.  For
     example, a `user' table entry with `Host' and `User' values of
     `'thomas.loc.gov'' and `'bob'' would be used for authenticating
     connections made to the server from the host `thomas.loc.gov' by a
     client that specifies a username of `bob'.  Similarly, a `db'
     table entry with `Host', `User', and `Db' column values of
     `'thomas.loc.gov'', `'bob'' and `'reports'' would be used when
     `bob' connects from the host `thomas.loc.gov' to access the
     `reports' database.  The `tables_priv' and `columns_priv' tables
     contain scope columns indicating tables or table/column
     combinations to which each entry applies.

   * Privilege columns indicate the privileges granted by a table
     entry; that is, what operations can be performed.  The server
     combines the information in the various grant tables to form a
     complete description of a user's privileges.  The rules used to do
     this are described in *Note Request access::.


Scope columns contain strings. They are declared as shown here; the
default value for each is the empty string:

*Column Name*  *Type*
`Host'         `CHAR(60)'
`User'         `CHAR(16)'
`Password'     `CHAR(16)'
`Db'           `CHAR(64)'
`Table_name'   `CHAR(60)'
`Column_name'  `CHAR(60)'

Before MySQL 3.23, the `Db' column is `CHAR(32)' in some tables and
`CHAR(60)' in others.

For access-checking purposes, comparisons of `Host' values are
case-insensitive.  `User', `Password', `Db', and `Table_name' values
are case sensitive.  `Column_name' values are case insensitive in MySQL
3.22.12 or later.

In the `user', `db', and `host' tables, each privilege is listed in a
separate column that is declared as `ENUM('N','Y') DEFAULT 'N''. In
other words, each privilege can disabled or enabled, with the default
being disabled.

In the `tables_priv' and `columns_priv' tables, the privilege columns
are declared as `SET' columns. Values in these columns can contain any
combination of the privileges controlled by the table:

*Table      *Column     *Possible Set Elements*
Name*       Name*
`tables_priv'`Table_priv'`'Select', 'Insert', 'Update',
                        'Delete', 'Create', 'Drop', 'Grant',
                        'References', 'Index', 'Alter''
`tables_priv'`Column_priv'`'Select', 'Insert', 'Update',
                        'References''
`columns_priv'`Column_priv'`'Select', 'Insert', 'Update',
                        'References''

Briefly, the server uses the grant tables as follows:

   * The `user' table scope columns determine whether to reject or allow
     incoming connections.  For allowed connections, any privileges
     granted in the `user' table indicate the user's global (superuser)
     privileges.  These privileges apply to _all_ databases on the
     server.

   * The `db' table scope columns determine which users can access which
     databases from which hosts.  The privilege columns determine which
     operations are allowed. A privilege granted at the database level
     applies to the database and to all its tables.

   * The `host' table is used in conjunction with the `db' table when
     you want a given `db' table entry to apply to several hosts.  For
     example, if you want a user to be able to use a database from
     several hosts in your network, leave the `Host' value empty in the
     user's `db' table entry, then populate the `host' table with an
     entry for each of those hosts.  This mechanism is described more
     detail in *Note Request access::.

     *Note*: The `host' table is not affected by the `GRANT' and
     `REVOKE' statements. Most MySQL installations need not use this
     table at all.

   * The `tables_priv' and `columns_priv' tables are similar to the
     `db' table, but are more fine-grained: They apply at the table and
     column levels rather than at the database level.  A privilege
     granted at the table level applies to the table and to all its
     columns.  A privilege granted at the column level applies only to
     a specific column.

Administrative privileges (such as `RELOAD' or `SHUTDOWN') are
specified only in the `user' table.  This is because administrative
operations are operations on the server itself and are not
database-specific, so there is no reason to list these privileges in the
other grant tables.  In fact, to determine whether you can perform an
administrative operation, the server need consult only the `user' table.

The `FILE' privilege also is specified only in the `user' table.  It is
not an administrative privilege as such, but your ability to read or
write files on the server host is independent of the database you are
accessing.

The `mysqld' server reads the contents of the grant tables into memory
when it starts. You can tell it to re-read the tables by issuing a
`FLUSH PRIVILEGES' statement or executing a `mysqladmin
flush-privileges' or `mysqladmin reload' command.  Changes to the grant
tables take effect as indicated in *Note Privilege changes::.

When you modify the contents of the grant tables, it is a good idea to
make sure that your changes set up privileges the way you want. One way
to check the privileges for a given account is to use the `SHOW GRANTS'
statement.  For example, to determine the privileges that are granted
to an account with `Host' and `User' values of `pc84.example.com' and
`bob', issue this statement:

     mysql> SHOW GRANTS FOR 'bob'@'pc84.example.com';

A useful diagnostic tool is the `mysqlaccess' script, which Yves
Carlier has provided for the MySQL distribution.  Invoke `mysqlaccess'
with the `--help' option to find out how it works.  Note that
`mysqlaccess' checks access using only the `user', `db', and `host'
tables.  It does not check table or column privileges specified in the
`tables_priv' or `columns_priv' tables.

For additional help in diagnosing privilege-related problems, see *Note
Access denied::.  For general advice on security issues, see *Note
Security::.

Privileges Provided by MySQL
----------------------------

Information about account privileges is stored in the `user', `db',
`host', `tables_priv', and `columns_priv' tables in the `mysql'
database.  The MySQL server reads the contents of these tables into
memory when it starts and re-reads them under the circumstances
indicated in *Note Privilege changes::.  Access-control decisions are
based on the in-memory copies of the grant tables.

The names used in this manual to refer to the privileges provided by
MySQL are shown in the following table, along with the table column name
associated with each privilege in the grant tables and the context in
which the privilege applies. Further information about the meaning of
each privilege may be found at *Note `GRANT': GRANT.

*Privilege* *Column*       *Context*
`ALTER'     `Alter_priv'   tables
`DELETE'    `Delete_priv'  tables
`INDEX'     `Index_priv'   tables
`INSERT'    `Insert_priv'  tables
`SELECT'    `Select_priv'  tables
`UPDATE'    `Update_priv'  tables
`CREATE'    `Create_priv'  databases, tables, or
                           indexes
`DROP'      `Drop_priv'    databases or tables
`GRANT'     `Grant_priv'   databases or tables
`REFERENCES'`References_priv'databases or tables
`CREATE     `Create_tmp_table_priv'server administration
TEMPORARY
TABLES'
`EXECUTE'   `Execute_priv' server administration
`FILE'      `File_priv'    file access on server
                           host
`LOCK       `Lock_tables_priv'server administration
TABLES'
`PROCESS'   `Process_priv' server administration
`RELOAD'    `Reload_priv'  server administration
`REPLICATION`Repl_client_priv'server administration
CLIENT'
`REPLICATION`Repl_slave_priv'server administration
SLAVE'
`SHOW       `Show_db_priv' server administration
DATABASES'
`SHUTDOWN'  `Shutdown_priv'server administration
`SUPER'     `Super_priv'   server administration

The `CREATE TEMPORARY TABLES', `EXECUTE', `LOCK TABLES', `REPLICATION
CLIENT', `REPLICATION SLAVE', `SHOW DATABASES', and `SUPER' privileges
were added in MySQL 4.0.2.

The `EXECUTE' and `REFERENCES' privileges currently are unused.

The `SELECT', `INSERT', `UPDATE', and `DELETE' privileges allow you to
perform operations on rows in existing tables in a database.

`SELECT' statements require the `SELECT' privilege only if they
actually retrieve rows from a table.  Some `SELECT' statements do not
access tables and can be executed without permission for any database.
For example, you can use the `mysql' client as a simple calculator to
evaluate expressions that make no reference to tables:

     mysql> SELECT 1+1;
     mysql> SELECT PI()*2;

The `CREATE' and `DROP' privileges allow you to create new databases
and tables, or to drop (remove) existing databases and tables.  If you
grant the `DROP' privilege for the `mysql' database to a user, that
user can drop the database in which the MySQL access privileges are
stored!

The `INDEX' privilege allows you to create or drop (remove) indexes.
`INDEX' applies to existing tables.  If you have the `CREATE' privilege
for a table, you can include index definitions in the `CREATE TABLE'
statement.

The `ALTER' privilege allows you to use `ALTER TABLE' to change the
structure of or rename tables.

The `GRANT' privilege allows you to give to other users those
privileges that you yourself possess.

The `FILE' privilege gives you permission to read and write files on
the server host using the `LOAD DATA INFILE' and `SELECT ... INTO
OUTFILE' statements. A user who has the `FILE' privilege can read any
file on the server host that is either world-readable or readable by
the MySQL server. (This implies the user can read any file in any
database directory, because the server can access any of those files.)
The `FILE' privilege also allows the user to create new files in any
directory where the MySQL server has write access. Existing files
cannot be overwritten.

The remaining privileges are used for administrative operations. Many of
them can be performed by using the `mysqladmin' program or by issuing
SQL statements.  The following table shows which `mysqladmin' commands
each administrative privilege allows you to execute:

*Privilege* *Commands Permitted to Privilege Holders*
`RELOAD'    `flush-hosts', `flush-logs', `flush-privileges',
            `flush-status', `flush-tables', `flush-threads',
            `refresh', `reload'
`SHUTDOWN'  `shutdown'
`PROCESS'   `processlist'
`SUPER'     `kill'

The `reload' command tells the server to re-read the grant tables into
memory.  `flush-privileges' is a synonym for `reload'.  The `refresh'
command closes and reopens the log files and flushes all tables.  The
other `flush-XXX' commands perform functions similar to `refresh', but
are more specific and may be preferable in some instances.  For
example, if you want to flush just the log files, `flush-logs' is a
better choice than `refresh'.

The `shutdown' command shuts down the server. This command can be issued
only from `mysqladmin'. There is no corresponding SQL statement.

The `processlist' command displays information about the threads
executing within the server (that is, about the statements being
executed by clients associated with other accounts).  The `kill'
command terminates server threads.  You can always display or kill your
own threads, but you need the `PROCESS' privilege to display threads
initiated by other users and the `SUPER' privilege to kill them.  *Note
`KILL': KILL. Prior to MySQL 4.0.2 when `SUPER' was introduced, the
`PROCESS' privilege controls the ability to both see and terminate
threads for other clients.

The `CREATE TEMPORARY TABLES' privilege allows the use of the keyword
`TEMPORARY' in `CREATE TABLE' statements.

The `LOCK TABLES' privilege allows the use of explicit `LOCK TABLES'
statements to lock tables for which you have the `SELECT' privilege.
This includes the use of write locks, which prevents anyone else from
reading the locked table.

The `REPLICATION CLIENT' privilege allows the use of `SHOW MASTER
STATUS' and `SHOW SLAVE STATUS'.

The `REPLICATION SLAVE' privilege should be granted to accounts that are
used by slave servers when they connect to the current server as their
master.  Without this privilege, the slave cannot request updates that
have been made to databases on the master server.

The `SHOW DATABASES' privilege allows the account to see database names
by issuing the `SHOW DATABASE' statement. Accounts that do not have this
privilege see only databases for which they have some privileges, and
cannot use the statement at all if the server was started with the
`--skip-show-database' option.

It is a good idea in general to grant privileges to only those accounts
that need them, but you should exercise particular caution in granting
administrative privileges:

   * The `GRANT' privilege allows users to give their privileges to
     other users.  Two users with different privileges and with the
     `GRANT' privilege are able to combine privileges.

   * The `ALTER' privilege may be used to subvert the privilege system
     by renaming tables.

   * The `FILE' privilege can be abused to read into a database table
     any files that the MySQL server can read on the server host. This
     includes all world-readable files and files in the server's data
     directory. The table can then be accessed using `SELECT' to
     transfer its contents to the client host.

   * The `SHUTDOWN' privilege can be abused to deny service to other
     users entirely by terminating the server.

   * The `PROCESS' privilege can be used to view the plain text of
     currently executing queries, including queries that set or change
     passwords.

   * The `SUPER' privilege can be used to terminate other clients or
     change how the server operates.

   * Privileges granted for the `mysql' database itself can be used to
     change passwords and other access privilege information.
     Passwords are stored encrypted, so a malicious user cannot simply
     read them to know the plain text password.  However, a user with
     write access to the `user' table `Password' column can change an
     account's password, and then connect to the MySQL server using
     that account.


There are some things that you cannot do with the MySQL privilege
system:

   * You cannot explicitly specify that a given user should be denied
     access.  That is, you cannot explicitly match a user and then
     refuse the connection.

   * You cannot specify that a user has privileges to create or drop
     tables in a database but not to create or drop the database itself.

Connecting to the MySQL Server
------------------------------

MySQL client programs generally expect you to specify connection
parameters when you want to access a MySQL server:

   * The name of the host where the MySQL server is running

   * Your username

   * Your password

For example, the `mysql' client can be started as follows from a
command-line prompt (indicated here by `shell>'):

     shell> mysql -h HOST_NAME -u USER_NAME -pYOUR_PASS

Alternate forms of the `-h', `-u', and `-p' options are
`--host=HOST_NAME', `--user=USER_NAME', and `--password=YOUR_PASS'.
Note that there is _no space_ between `-p' or `--password=' and the
password following it.

If you use a `-p' or `--password' option but do not specify the
password value, the client program will prompt you to enter the
password.  The password is not displayed as you enter it.  This is more
secure than giving the password on the command line.  Any user on your
system may be able to see a password specified on the command line by
executing a command such as `ps auxww'.  *Note Password security::.

MySQL client programs use default values for any connection parameter
option that you do not specify:

   * The default hostname is `localhost'.

   * The default username is `ODBC' on Windows and your Unix login name
     on Unix.

   * No password is supplied if `-p' is missing.

Thus, for a Unix user with a login name of `joe', all of the following
commands are equivalent:

     shell> mysql -h localhost -u joe
     shell> mysql -h localhost
     shell> mysql -u joe
     shell> mysql

Other MySQL clients behave similarly.

You can specify different default values to be used when you make a
connection so that you need not enter them on the command line each
time you invoke a client program.  This can be done in a couple of ways:

   * You can specify connection parameters in the `[client]' section of
     an option file.  The relevant section of the file might look like
     this:

          [client]
          host=HOST_NAME
          user=USER_NAME
          password=YOUR_PASS

     Option files are discussed further in *Note Option files::.

   * You can specify some connection parameters using environment
     variables.  The host can be specified for `mysql' using
     `MYSQL_HOST'.  The MySQL username can be specified using `USER'
     (this is for Windows and NetWare only).  The password can be
     specified using `MYSQL_PWD', although this is insecure; see *Note
     Password security::.  For a list of variables, see *Note
     Environment variables::.

Access Control, Stage 1: Connection Verification
------------------------------------------------

When you attempt to connect to a MySQL server, the server accepts or
rejects the connection based on your identity and whether you can
verify your identity by supplying the correct password.  If not, the
server denies access to you completely.  Otherwise, the server accepts
the connection, then enters Stage 2 and waits for requests.

Your identity is based on two pieces of information:

   * The client host from which you connect

   * Your MySQL username

Identity checking is performed using the three `user' table scope
columns (`Host', `User', and `Password').  The server accepts the
connection only if the `Host' and `User' columns in some `user' table
record match the client hostname and username, and the client supplies
the password specified in that record.

`Host' values in the `user' table may be specified as follows:

   * A `Host' value may be a hostname or an IP number, or `'localhost''
     to indicate the local host.

   * You can use the wildcard characters `%' and `_' in `Host' column
     values.  These have the same meaning as for pattern-matching
     operations performed with the `LIKE' operator.  For example, a
     `Host' value of `'%'' matches any hostname, whereas a value of
     `'%.mysql.com'' matches any host in the `mysql.com' domain.

   * As of MySQL 3.23, for `Host' values specified as IP numbers, you
     can specify a netmask indicating how many address bits to use for
     the network number. For example:

          mysql> GRANT ALL PRIVILEGES ON db.*
              -> TO david@'192.58.197.0/255.255.255.0';

     This allows `david' to connect from any client host having an IP
     number `client_ip' for which the following condition is true:

          client_ip & netmask = host_ip

     That is, for the `GRANT' statement just shown:

          client_ip & 255.255.255.0 = 192.58.197.0

     IP numbers that satisfy this condition and can connect to the
     MySQL server are those that lie in the range from `192.58.197.0' to
     `192.58.197.255'.

   * A blank `Host' value in a `db' table record means that its
     privileges should be combined with those in the entry in the `host'
     table that matches the client hostname.  The privileges are
     combined using an AND (intersection) operation, not OR (union).
     You can find more information about the `host' table in *Note
     Request access::.

     A blank `Host' value in the other grant tables is the same as
     `'%''.


Because you can use IP wildcard values in the `Host' column (for
example, `'144.155.166.%'' to match every host on a subnet), someone
could try to exploit this capability by naming a host
`144.155.166.somewhere.com'.  To foil such attempts, MySQL disallows
matching on hostnames that start with digits and a dot. Thus, if you
have a host named something like `1.2.foo.com', its name will never
match the `Host' column of the grant tables.  An IP wildcard value can
match only IP numbers, not hostnames.

In the `User' column, wildcard characters are not allowed, but you can
specify a blank value, which matches any name.  If the `user' table
entry that matches an incoming connection has a blank username, the
user is considered to be an anonymous user with no name, not a user
with the name that the client actually specified.  This means that a
blank username is used for all further access checking for the duration
of the connection (that is, during Stage 2).

The `Password' column can be blank.  This is not a wildcard and does
not mean that any password matches. It means that the user must connect
without specifying a password.

Non-blank `Password' values in the `user' table represent encrypted
passwords.  MySQL does not store passwords in plaintext form for anyone
to see.  Rather, the password supplied by a user who is attempting to
connect is encrypted (using the `PASSWORD()' function). The encrypted
password then is used during the connection process when checking
whether the password is correct. (This is done without the encrypted
password ever traveling over the connection.)  From MySQL's point of
view, the encrypted password is the REAL password, so you should not
give anyone access to it!  In particular, don't give non-administrative
users read access to the tables in the `mysql' database!

From version 4.1 on, MySQL employs a stronger authentication method
that has better password protection during the connection process than
in earlier versions. It is secure even if TCP/IP packets are sniffed or
the `mysql' database is captured.  Password encryption is discussed
further in *Note Password hashing::.

The following examples show how various combinations of `Host' and
`User' values in the `user' table apply to incoming connections:

`Host' *Value*            `User'      *Connections Matched by Entry*
                          *Value*
`'thomas.loc.gov''        `'fred''    `fred', connecting from
                                      `thomas.loc.gov'
`'thomas.loc.gov''        `'''        Any user, connecting from
                                      `thomas.loc.gov'
`'%''                     `'fred''    `fred', connecting from any host
`'%''                     `'''        Any user, connecting from any host
`'%.loc.gov''             `'fred''    `fred', connecting from any host in
                                      the `loc.gov' domain
`'x.y.%''                 `'fred''    `fred', connecting from `x.y.net',
                                      `x.y.com', `x.y.edu', and so on.
                                      (this is probably not useful)
`'144.155.166.177''       `'fred''    `fred', connecting from the host
                                      with IP address `144.155.166.177'
`'144.155.166.%''         `'fred''    `fred', connecting from any host in
                                      the `144.155.166' class C subnet
`'144.155.166.0/255.255.255.0''`'fred''    Same as previous example

It is possible for the client hostname and username of an incoming
connection to match more than one entry in the `user' table.  The
preceding set of examples demonstrates this: Several of the entries
shown match a connection from `thomas.loc.gov' by `fred'.

When multiple matches are possible, the server must determine which of
them to use.  It resolves this issue as follows:

   * Whenever the server reads the `user' table into memory, it sorts
     the entries.

   * When a client attempts to connect, the server looks through the
     entries in sorted order.

   * The server uses the first entry that matches the client hostname
     and username.

To see how this works, suppose that the `user' table looks like this:

     +-----------+----------+-
     | Host      | User     | ...
     +-----------+----------+-
     | %         | root     | ...
     | %         | jeffrey  | ...
     | localhost | root     | ...
     | localhost |          | ...
     +-----------+----------+-

When the server reads in the table, it orders the entries with the
most-specific `Host' values first.  Literal hostnames and IP numbers
are the most specific. The pattern `'%'' means "any host" and is least
specific.  Entries with the same `Host' value are ordered with the
most-specific `User' values first (a blank `User' value means "any
user" and is least specific). For the `user' table just shown, the
result after sorting looks like this:

     +-----------+----------+-
     | Host      | User     | ...
     +-----------+----------+-
     | localhost | root     | ...
     | localhost |          | ...
     | %         | jeffrey  | ...
     | %         | root     | ...
     +-----------+----------+-

When a client attempts to connect, the server looks through the sorted
entries and uses the first match found.  For a connection from
`localhost' by `jeffrey', two of the entries in the table match: the
one with `Host' and `User' values of `'localhost'' and `''', and the
one with values of `'%'' and `'jeffrey''.  The `'localhost'' entry
appears first in sorted order, so that is the one the server uses.

Here is another example.  Suppose that the `user' table looks like this:

     +----------------+----------+-
     | Host           | User     | ...
     +----------------+----------+-
     | %              | jeffrey  | ...
     | thomas.loc.gov |          | ...
     +----------------+----------+-

The sorted table looks like this:

     +----------------+----------+-
     | Host           | User     | ...
     +----------------+----------+-
     | thomas.loc.gov |          | ...
     | %              | jeffrey  | ...
     +----------------+----------+-

A connection by `jeffrey' from `thomas.loc.gov' is matched by the first
entry, whereas a connection by `jeffrey' from `whitehouse.gov' is
matched by the second.

It is a common misconception to think that, for a given username, all
entries that explicitly name that user will be used first when the
server attempts to find a match for the connection.  This is simply not
true.  The previous example illustrates this, where a connection from
`thomas.loc.gov' by `jeffrey' is first matched not by the entry
containing `'jeffrey'' as the `User' column value, but by the entry
with no username!  As a result, `jeffrey' will be authenticated as an
anonymous user, even though he specified a username when connecting.

If you are able to connect to the server, but your privileges are not
what you expect, you probably are being authenticated as some other
account.  To find out what account the server used to authenticate you,
use the `CURRENT_USER()' function. It returns a value in
`USER_NAME@HOST_NAME' format that indicates the `User' and `Host'
values from the matching `user' table record.  Suppose that `jeffrey'
connects and issues the following query:

     mysql> SELECT CURRENT_USER();
     +----------------+
     | CURRENT_USER() |
     +----------------+
     | @localhost     |
     +----------------+

The result shown here indicates that the matching `user' table entry
had a blank `User' column value.  In other words, the server is
treating `jeffrey' as an anonymous user.

The `CURRENT_USER()' function is available as of MySQL 4.0.6.  *Note
Information functions::.  Another thing you can do to diagnose
authentication problems is to print out the `user' table and sort it by
hand to see where the first match is being made.

Access Control, Stage 2: Request Verification
---------------------------------------------

Once you establish a connection, the server enters Stage 2 of access
control.  For each request that comes in on the connection, the server
determines what operation you want to perform, then checks whether you
have sufficient privileges to do so.  This is where the privilege
columns in the grant tables come into play.  These privileges can come
from any of the `user', `db', `host', `tables_priv', or `columns_priv'
tables.  (You may find it helpful to refer to *Note Privileges::, which
lists the columns present in each of the grant tables.)

The `user' table grants privileges that are assigned to you on a global
basis and that apply no matter what the current database is.  For
example, if the `user' table grants you the `DELETE' privilege, you can
delete rows from any table in any database on the server host!  In
other words, `user' table privileges are superuser privileges.  It is
wise to grant privileges in the `user' table only to superusers such as
database administrators.  For other users, you should leave the
privileges in the `user' table set to `'N'' and grant privileges at more
specific levels only. You can grant privileges for particular databases,
tables, or columns.

The `db' and `host' tables grant database-specific privileges.  Values
in the scope columns of these tables can take the following forms:

   * The wildcard characters `%' and `_' can be used in the `Host' and
     `Db' columns of either table.  These have the same meaning as for
     pattern-matching operations performed with the `LIKE' operator.
     If you want to use either character literally when granting
     privileges, you must escape it with a backslash.  For example, to
     include `_' character as part of a database name, specify it as
     `\_' in the `GRANT' statement.

   * A `'%'' `Host' value in the `db' table means "any host." A blank
     `Host' value in the `db' table means "consult the `host' table for
     further information" (a process that is described later in this
     section).

   * A `'%'' or blank `Host' value in the `host' table means "any host."

   * A `'%'' or blank `Db' value in either table means "any database."

   * A blank `User' value in either table matches the anonymous user.

The server reads in and sorts the `db' and `host' tables at the same
time that it reads the `user' table.  The server sorts the `db' table
based on the `Host', `Db', and `User' scope columns, and sorts the
`host' table based on the `Host' and `Db' scope columns.  As with the
`user' table, sorting puts the most-specific values first and
least-specific values last, and when the server looks for matching
entries, it uses the first match that it finds.

The `tables_priv' and `columns_priv' tables grant table-specific and
column-specific privileges.  Values in the scope columns of these
tables can take the following form:

   * The wildcard characters `%' and `_' can be used in the `Host'
     column of either table.  These have the same meaning as for
     pattern-matching operations performed with the `LIKE' operator.

   * A `'%'' or blank `Host' value in either table means "any host."

   * The `Db', `Table_name', and `Column_name' columns cannot contain
     wildcards or be blank in either table.

The server sorts the `tables_priv' and `columns_priv' tables based on
the `Host', `Db', and `User' columns.  This is similar to `db' table
sorting, but simpler because only the `Host' column can contain
wildcards.

The request verification process is described here.  (If you are
familiar with the access-checking source code, you will notice that the
description here differs slightly from the algorithm used in the code.
The description is equivalent to what the code actually does; it
differs only to make the explanation simpler.)

For requests that require administrative privileges such as `SHUTDOWN'
or `RELOAD', the server checks only the `user' table entry because that
is the only table that specifies administrative privileges.  Access is
granted if the entry allows the requested operation and denied
otherwise.  For example, if you want to execute `mysqladmin shutdown'
but your `user' table entry doesn't grant the `SHUTDOWN' privilege to
you, the server denies access without even checking the `db' or `host'
tables.  (They contain no `Shutdown_priv' column, so there is no need
to do so.)

For database-related requests (`INSERT', `UPDATE', and so on), the
server first checks the user's global (superuser) privileges by looking
in the `user' table entry.  If the entry allows the requested operation,
access is granted.  If the global privileges in the `user' table are
insufficient, the server determines the user's database-specific
privileges by checking the `db' and `host' tables:

  1. The server looks in the `db' table for a match on the `Host',
     `Db', and `User' columns.  The `Host' and `User' columns are
     matched to the connecting user's hostname and MySQL username.  The
     `Db' column is matched to the database that the user wants to
     access.  If there is no entry for the `Host' and `User', access is
     denied.

  2. If there is a matching `db' table entry and its `Host' column is
     not blank, that entry defines the user's database-specific
     privileges.

  3. If the matching `db' table entry's `Host' column is blank, it
     signifies that the `host' table enumerates which hosts should be
     allowed access to the database.  In this case, a further lookup is
     done in the `host' table to find a match on the `Host' and `Db'
     columns.  If no `host' table entry matches, access is denied.  If
     there is a match, the user's database-specific privileges are
     computed as the intersection (_not_ the union!) of the privileges
     in the `db' and `host' table entries; that is, the privileges that
     are `'Y'' in both entries.  (This way you can grant general
     privileges in the `db' table entry and then selectively restrict
     them on a host-by-host basis using the `host' table entries.)

After determining the database-specific privileges granted by the `db'
and `host' table entries, the server adds them to the global privileges
granted by the `user' table.  If the result allows the requested
operation, access is granted.  Otherwise, the server successively
checks the user's table and column privileges in the `tables_priv' and
`columns_priv' tables, adds those to the user's privileges, and allows
or denies access based on the result.

Expressed in boolean terms, the preceding description of how a user's
privileges are calculated may be summarized like this:

     global privileges
     OR (database privileges AND host privileges)
     OR table privileges
     OR column privileges

It may not be apparent why, if the global `user' entry privileges are
initially found to be insufficient for the requested operation, the
server adds those privileges to the database, table, and column
privileges later. The reason is that a request might require more than
one type of privilege.  For example, if you execute an `INSERT INTO ...
SELECT' statement, you need both the `INSERT' and the `SELECT'
privileges.  Your privileges might be such that the `user' table entry
grants one privilege and the `db' table entry grants the other.  In
this case, you have the necessary privileges to perform the request,
but the server cannot tell that from either table by itself; the
privileges granted by the entries in both tables must be combined.

The `host' table is not affected by the `GRANT' or `REVOKE' statements,
so it is unused in most MySQL installations. If you modify it directly,
you can use it for some specialized purposes, such as to to maintain a
list of secure servers.  For example, at TcX, the `host' table contains
a list of all machines on the local network. These are granted all
privileges.

You can also use the `host' table to indicate hosts that are _not_
secure.  Suppose that you have a machine `public.your.domain' that is
located in a public area that you do not consider secure.  You can
allow access to all hosts on your network except that machine by using
`host' table entries like this:

     +--------------------+----+-
     | Host               | Db | ...
     +--------------------+----+-
     | public.your.domain | %  | ... (all privileges set to 'N')
     | %.your.domain      | %  | ... (all privileges set to 'Y')
     +--------------------+----+-

Naturally, you should always test your entries in the grant tables (for
example, by using `SHOW GRANTS' or `mysqlaccess') to make sure that
your access privileges are actually set up the way you think they are.

When Privilege Changes Take Effect
----------------------------------

When `mysqld' starts, all grant table contents are read into memory and
become effective for access control at that point.

When the server reloads the grant tables, privileges for existing
client connections are affected as follows:

   * Table and column privilege changes take effect with the client's
     next request.

   * Database privilege changes take effect at the next `USE DB_NAME'
     statement.

   * Changes to global privileges and passwords take effect the next
     time the client connects.

If you modify the grant tables using `GRANT', `REVOKE', or `SET
PASSWORD', the server notices these changes and reloads the grant
tables into memory again immediately.

If you modify the grant tables directly using statements such as
`INSERT', `UPDATE', or `DELETE', your changes have no effect on
privilege checking until you either restart the server or tell it to
reload the tables.  To reload the grant tables manually, issue a `FLUSH
PRIVILEGES' statement or execute a `mysqladmin flush-privileges' or
`mysqladmin reload' command.

If you change the grant tables directly but forget to reload them, your
changes will have _no effect_ until you restart the server.  This may
leave you wondering why your changes don't seem to make any difference!

Causes of `Access denied' Errors
--------------------------------

If you encounter problems when you try to connect to the MySQL server,
the following items describe some courses of action you can take to
correct the problem.

   * Make sure that the server is running. If it is not running, you
     cannot connect to it.  For example, if you attempt to connect to
     the server and see a message such as one of those following, one
     cause might be that the server is not running:

          shell> mysql
          ERROR 2003: Can't connect to MySQL server on 'HOST_NAME' (111)
          shell> mysql
          ERROR 2002: Can't connect to local MySQL server through socket
          '/tmp/mysql.sock' (111)

     It might also be that the server is running, but you are trying to
     connect using a TCP/IP port, named pipe, or Unix socket file
     different from those on which the server is listening. To correct
     this when you invoke a client program, specify a `--port' option
     to indicate the proper port, or a `--socket' option to indicate
     the proper named pipe or Unix socket file.  To find out what port
     is used, and where the socket is, you can do:

          shell> netstat -l | grep mysql

   * The grant tables must be properly set up so that the server can
     use them for access control.  For some distribution types (such as
     binary distributions on Windows on RPM distributions on Linux),
     the installation process initializes the `mysql' database
     containing the grant tables.  For distributions that do not do
     this, you should initialize the grant tables manually by running
     the `mysql_install_db' script.  For details, see *Note Unix
     post-installation::.

     One way to determine whether you need to initialize the grant
     tables is to look for a `mysql' directory under the data
     directory. (The data directory normally is named `data' or `var'
     and is located under your MySQL installation directory.)  Make
     sure that you have a file named `user.MYD' in the `mysql' database
     directory.  If you do not, execute the `mysql_install_db' script.
     After running this script and starting the server, test the
     initial privileges by executing this command:

          shell> mysql -u root test

     The server should let you connect without error.

   * After a fresh installation, you should connect to the server and
     set up your users and their access permissions:

          shell> mysql -u root mysql

     The server should let you connect because the MySQL `root' user
     has no password initially.  That is also a security risk, so
     setting the password for the `root' accounts is something you
     should do while you're setting up your other MySQL users.  For
     instructions on setting the initial passwords, see *Note Default
     privileges::.

   * If you have updated an existing MySQL installation to a newer
     version, did you run the `mysql_fix_privilege_tables' script?  If
     not, do so. The structure of the grant tables changes occasionally
     when new capabilities are added, so after an upgrade you should
     always make sure that your tables have the current structure. For
     instructions, see *Note Upgrading-grant-tables::.

   * If a client program receives the following error message when it
     tries to connect, it means that the server expects passwords in a
     newer format than the client is capable of generating:

          shell> mysql
          Client does not support authentication protocol requested
          by server; consider upgrading MySQL client

     For information on how to deal with this, see *Note Password
     hashing:: and *Note Old client::.

   * If you try to connect as `root' and get the following error, it
     means that you don't have an entry in the `user' table with a
     `User' column value of `'root'' and that `mysqld' cannot resolve
     the hostname for your client:

          Access denied for user ''@'unknown' to database mysql

     In this case, you must restart the server with the
     `--skip-grant-tables' option and edit your `/etc/hosts' or
     `\windows\hosts' file to add an entry for your host.

   * Remember that client programs will use connection parameters
     specified in option files or environment variables.  If a client
     program seems to be sending incorrect default connection
     parameters when you don't specify them on the command line, check
     your environment and any applicable option files. For example, if
     you get `Access denied' when you run a client without any options,
     make sure that you haven't specified an old password in any of
     your option files!

     You can suppress the use of option files by a client program by
     invoking it with the `--no-defaults' option. For example:

          shell> mysqladmin --no-defaults -u root version

     The option files that clients use are listed in *Note Option
     files::.  Environment variables are listed in *Note Environment
     variables::.

   * If you get the following error, it means that you are using an
     incorrect `root' password:

          shell> mysqladmin -u root -pXXXX ver
          Access denied for user 'root'@'localhost' (using password: YES)

     If the preceding error occurs even when you haven't specified a
     password, it means that you have an incorrect password listed in
     some option file. Try the `--no-defaults' option as described in
     the previous item.

     For information on changing passwords, see *Note Passwords::.

     If you have lost or forgotten the `root' password, you can restart
     `mysqld' with `--skip-grant-tables' to change the password.  *Note
     Resetting permissions::.

   * If you change a password by using `SET PASSWORD', `INSERT', or
     `UPDATE', you must encrypt the password using the `PASSWORD()'
     function.  If you do not use `PASSWORD()' for these statements,
     the password will not work. For example, the following statement
     sets a password, but fails to encrypt it, so the user will not be
     able to connect afterward:

          mysql> SET PASSWORD FOR 'abe'@'HOST_NAME' = 'eagle';

     Instead, set the password like this:

          mysql> SET PASSWORD FOR 'abe'@'HOST_NAME' = PASSWORD('eagle');

     The `PASSWORD()' function is unnecessary when you specify a
     password using the `GRANT' statement or the `mysqladmin password'
     command, both of which automatically use `PASSWORD()' to encrypt
     the password.  *Note Passwords::.

   * `localhost' is a synonym for your local hostname, and is also the
     default host to which clients try to connect if you specify no host
     explicitly.  However, connections to `localhost' on Unix systems
     do not work if you are using a MySQL version older than 3.23.27
     that uses MIT-pthreads: `localhost' connections are made using
     Unix socket files, which were not supported by MIT-pthreads at
     that time.

     To avoid this problem on such systems, you can use a
     `--host=127.0.0.1' option to name the server host explicitly.
     This will make a TCP/IP connection to the local `mysqld' server.
     You can also use TCP/IP by specifying a `--host' option that uses
     the actual hostname of the local host.  In this case, the hostname
     must be specified in a `user' table entry on the server host, even
     though you are running the client program on the same host as the
     server.

   * If you get an `Access denied' error when trying to connect to the
     database with `mysql -u user_name', you may have a problem with
     the `user' table. Check this by executing `mysql -u root mysql'
     and issuing this SQL statement:

          mysql> SELECT * FROM user;

     The result should include an entry with the `Host' and `User'
     columns matching your computer's hostname and your MySQL username.

   * The `Access denied' error message will tell you who you are trying
     to log in as, the client host from which you are trying to
     connect, and whether or not you were using a password. Normally,
     you should have one entry in the `user' table that exactly matches
     the hostname and username that were given in the error message.
     For example, if you get an error message that contains `using
     password: NO', it means that you tried to log in without an
     password.

   * If the following error occurs when you try to connect from a host
     other than the one on which the MySQL server is running, it means
     that there is no row in the `user' table with a `Host' value that
     matches the client host:

          Host ... is not allowed to connect to this MySQL server

     You can fix this by setting up an account for the combination of
     client hostname and username that you are using when trying to
     connect.

     If you don't know the IP number or hostname of the machine from
     which you are connecting, you should put an entry with `'%'' as
     the `Host' column value in the `user' table and restart `mysqld'
     with the `--log' option on the server machine.  After trying to
     connect from the client machine, the information in the MySQL log
     will indicate how you really did connect.  (Then change the `'%''
     in the `user' table entry to the actual hostname that shows up in
     the log.  Otherwise, you'll have a system that is insecure because
     it allows connections from any host for the given username.)

     On Linux, another reason that this error might occur is that you
     are using a binary MySQL version that is compiled with a different
     version of the `glibc' library than the one you are using.  In
     this case, you should either upgrade your operating system or
     `glibc', or download a source distribution of MySQL version and
     compile it yourself.  A source RPM is normally trivial to compile
     and install, so this isn't a big problem.

   * If you specify a hostname when trying to connect, but get an error
     message where the hostname is not shown or is an IP number, it
     means that the MySQL server got an error when trying to resolve the
     IP number of the client host to a name:

          shell> mysqladmin -u root -pXXXX -h SOME-HOSTNAME ver
          Access denied for user 'root'@'' (using password: YES)

     This indicates a DNS problem.  To fix it, execute `mysqladmin
     flush-hosts' to reset the internal DNS hostname cache. *Note DNS::.

     Some permanent solutions are:

        - Try to find out what is wrong with your DNS server and fix it.

        - Specify IP numbers rather than hostnames in the MySQL grant
          tables.

        - Put an entry for the client machine name in `/etc/hosts'.

        - Start `mysqld' with the `--skip-name-resolve' option.

        - Start `mysqld' with the `--skip-host-cache' option.

        - On Unix, if you are running the server and the client on the
          same machine, connect to `localhost'. Unix connections to
          `localhost' use a Unix socket file rather than TCP/IP.

        - On Windows, if you are running the server and the client on
          the same machine and the server supports named pipe
          connections, connect to the hostname `.' (period).
          Connections to `.' use a named pipe rather than TCP/IP.

   * If `mysql -u root test' works but `mysql -h YOUR_HOSTNAME -u root
     test' results in `Access denied' (where YOUR_HOSTNAME is the
     actual hostname of the local host), you may not have the correct
     name for your host in the `user' table.  A common problem here is
     that the `Host' value in the user table entry specifies an
     unqualified hostname, but your system's name resolution routines
     return a fully qualified domain name (or vice versa).  For
     example, if you have an entry with host `'tcx'' in the `user'
     table, but your DNS tells MySQL that your hostname is
     `'tcx.subnet.se'', the entry will not work. Try adding an entry to
     the `user' table that contains the IP number of your host as the
     `Host' column value.  (Alternatively, you could add an entry to the
     `user' table with a `Host' value that contains a wildcard; for
     example, `'tcx.%''.  However, use of hostnames ending with `%' is
     _insecure_ and is _not_ recommended!)

   * If `mysql -u USER_NAME test' works but `mysql -u USER_NAME
     OTHER_DB_NAME' does not, you have not granted database access for
     OTHER_DB_NAME to the given user.

   * If `mysql -u USER_NAME' works when executed on the server host, but
     `mysql -h HOST_NAME -u USER_NAME' doesn't work when executed on a
     remote client host, you have not enabled access to the server for
     the given username from the remote host.

   * If you can't figure out why you get `Access denied', remove from
     the `user' table all entries that have `Host' values containing
     wildcards (entries that contain `%' or `_').  A very common error
     is to insert a new entry with `Host'=`'%'' and
     `User'=`'SOME_USER'', thinking that this will allow you to specify
     `localhost' to connect from the same machine.  The reason that this
     doesn't work is that the default privileges include an entry with
     `Host'=`'localhost'' and `User'=`'''.  Because that entry has a
     `Host' value `'localhost'' that is more specific than `'%'', it is
     used in preference to the new entry when connecting from
     `localhost'!  The correct procedure is to insert a second entry
     with `Host'=`'localhost'' and `User'=`'SOME_USER'', or to delete
     the entry with `Host'=`'localhost'' and `User'=`'''.  After
     deleting the entry, remember to issue a `FLUSH PRIVILEGES'
     statement to reload the grant tables.

   * If you get the following error, you may have a problem with the
     `db' or `host' table:

          Access to database denied

     If the entry selected from the `db' table has an empty value in the
     `Host' column, make sure that there are one or more corresponding
     entries in the `host' table specifying which hosts the `db' table
     entry applies to.

   * If you are able to connect to the MySQL server, but get an `Access
     denied' message whenever you issue a `SELECT ...  INTO OUTFILE' or
     `LOAD DATA INFILE' statement, your entry in the `user' table
     doesn't have the `FILE' privilege enabled.

   * If you change the grant tables directly (for example, by using
     `INSERT', `UPDATE', or `DELETE' statements) and your changes seem
     to be ignored, remember that you must execute a `FLUSH PRIVILEGES'
     statement or a `mysqladmin flush-privileges' command to cause the
     server to re-read the privilege tables. Otherwise, your changes
     have no effect until the next time the server is restarted.
     Remember that after you change the `root' password with an
     `UPDATE' command, you won't need to specify the new password until
     after you flush the privileges, because the server won't know
     you've changed the password yet!

   * If your privileges seem to have changed in the middle of a
     session, it may be that a MySQL administrator has changed them.
     Reloading the grant tables affects new client connections, but it
     also affects existing connections as indicated in *Note Privilege
     changes::.

   * If you have access problems with a Perl, PHP, Python, or ODBC
     program, try to connect to the server with `mysql -u USER_NAME
     DB_NAME' or `mysql -u USER_NAME -pYOUR_PASS DB_NAME'.  If you are
     able to connect using the `mysql' client, the problem lies with
     your program, not with the access privileges.  (There is no space
     between `-p' and the password; you can also use the
     `--password=YOUR_PASS' syntax to specify the password. If you use
     the `-p' option alone, MySQL will prompt you for the password.)

   * For testing, start the `mysqld' server with the
     `--skip-grant-tables' option.  Then you can change the MySQL grant
     tables and use the `mysqlaccess' script to check whether your
     modifications have the desired effect.  When you are satisfied
     with your changes, execute `mysqladmin flush-privileges' to tell
     the `mysqld' server to start using the new grant tables.
     (Reloading the grant tables overrides the `--skip-grant-tables'
     option.  This allows you to tell the server to begin using the
     grant tables again without stopping and restarting it.)

   * If everything else fails, start the `mysqld' server with a
     debugging option (for example, `--debug=d,general,query'). This
     will print host and user information about attempted connections,
     as well as information about each command issued. *Note Making
     trace files::.

   * If you have any other problems with the MySQL grant tables and
     feel you must post the problem to the mailing list, always provide
     a dump of the MySQL grant tables. You can dump the tables with the
     `mysqldump mysql' command. As always, post your problem using the
     `mysqlbug' script.  *Note Bug reports::.  In some cases, you may
     need to restart `mysqld' with `--skip-grant-tables' to run
     `mysqldump'.


Password Hashing in MySQL 4.1
-----------------------------

MySQL user accounts are listed in the `user' table of the `mysql'
database. Each MySQL account is assigned a password, although what is
stored in the `Password' column of the `user' table is not the
plaintext version of the password, but a hash value computed from it.
Password hash values are computed by the `PASSWORD()' function.

MySQL uses passwords in two phases of client/server communication:

   * When a client attempts to connect to the server, there is an
     initial authentication step in which the client must present a
     password that has a hash value matching the hash value stored in
     the `user' table for the account that the client wants to use.

   * After the client connects, it can (if it has sufficient
     privileges) set or change the password hashes for accounts listed
     in the `user' table.  The client can do this by using the
     `PASSWORD()' function to generate a password hash, or by using the
     `GRANT' or `SET PASSWORD' statements.


In other words, the server _uses_ hash values during authentication when
a client first attempts to connect. The server _generates_ hash values
if a connected client invokes the `PASSWORD()' function or uses a
`GRANT' or `SET PASSWORD' statement to set or change a password.

The password hashing mechanism was updated in MySQL 4.1 to provide
better security and to reduce the risk of passwords being intercepted.
However, this new mechanism is understood only by the 4.1 server and
4.1 clients, which can result in some compatibility problems.  A 4.1
client can connect to a pre-4.1 server, because the client understands
both the old and new password hashing mechanisms. However, a pre-4.1
client that attempts to connect to a 4.1 server may run into
difficulties.  For example, a 4.0 `mysql' client that attempts to
connect to a 4.1 server may fail with the following error message:

     shell> mysql -h localhost -u root
     Client does not support authentication protocol requested
     by server; consider upgrading MySQL client

The following discussion describes the differences between the old and
new password mechanisms, and what you should do if you upgrade your
server to 4.1 but need to maintain backward compatibility with pre-4.1
clients. Additional information can be found in *Note Old client::.

*Note*: This discussion contrasts 4.1 behavior with pre-4.1 behavior,
but the 4.1 behavior described here actually begins with 4.1.1. MySQL
4.1.0 is an "odd" release because it has a slightly different mechanism
than that implemented in 4.1.1 and up.  Differences between 4.1.0 and
more recent versions are described further in *Note Password hashing
4.1.0::.

Prior to MySQL 4.1, password hashes computed by the `PASSWORD()'
function are 16 bytes long.  Such hashes look like this:

     mysql> SELECT PASSWORD('mypass');
     +--------------------+
     | PASSWORD('mypass') |
     +--------------------+
     | 6f8c114b58f2ce9e   |
     +--------------------+

The `Password' column of the `user' table (in which these hashes are
stored) also is 16 bytes long before MySQL 4.1.

As of MySQL 4.1, the `PASSWORD()' function has been modified to produce
a longer 41-byte hash value:

     mysql> SELECT PASSWORD('mypass');
     +-----------------------------------------------+
     | PASSWORD('mypass')                            |
     +-----------------------------------------------+
     | *43c8aa34cdc98eddd3de1fe9a9c2c2a9f92bb2098d75 |
     +-----------------------------------------------+

Accordingly, the `Password' column in the `user' table also must be 41
bytes long to store these values:

   * If you perform a new installation of MySQL 4.1, the `Password'
     column will be made 41 bytes long automatically.

   * If you upgrade an older installation to 4.1, you should run the
     `mysql_fix_privilege_tables' script to increase the length of the
     `Password' column from 16 to 41 bytes. (The script does not change
     existing password values, which remain 16 bytes long.)


A widened `Password' column can store password hashes in both the old
and new formats. The format of any given password hash value can be
determined two ways:

   * The obvious difference is the length (16 bytes versus 41 bytes).

   * A second difference is that password hashes in the new format
     always begin with a `*' character, whereas passwords in the old
     format never do.


The longer password hash format has better cryptographic properties, and
client authentication based on long hashes is more secure than that
based on the older short hashes.

The differences between short and long password hashes are relevant
both for how the server uses passwords during authentication and for
how it generates password hashes for connected clients that perform
password-changing operations.

The way in which the server uses password hashes during authentication
is affected by the width of the `Password' column:

   * If the column is short, only short-hash authentication is used.

   * If the column is long, it can hold either short or long hashes, and
     the server can use either format:

        - Pre-4.1 clients can connect, although because they know only
          about the old hashing mechanism, they can authenticate only
          for accounts that have short hashes.

        - 4.1 clients can authenticate for accounts that have short or
          long hashes.



For short-hash accounts, the authentication process is actually a bit
more secure for 4.1 clients than for older clients.  In terms of
security, the gradient from least to most secure is:

   * Pre-4.1 client authenticating for account with short password hash

   * 4.1 client authenticating for account with short password hash

   * 4.1 client authenticating for account with long password hash


The way in which the server generates password hashes for connected
clients is affected by the width of the `Password' column and by the
`--old-passwords' option.  A 4.1 server generates long hashes only if
certain conditions are met: The `Password' column must be wide enough
to hold long values and the `--old-passwords' option must not be given.
These conditions apply as follows:

   * The `Password' column must be wide enough to hold long hashes (41
     bytes).  If the column has not been updated and still has the
     pre-4.1 width of 16 bytes, the server notices that long hashes
     cannot fit into it and generates only short hashes when a client
     performs password-changing operations using `PASSWORD()', `GRANT',
     or `SET PASSWORD'.  This is the behavior that occurs if you have
     upgraded to 4.1 but have not yet run the
     `mysql_fix_privilege_tables' script to widen the `Password' column.

   * If the `Password' column is wide, it can store either short or long
     password hashes. In this case, `PASSWORD()', `GRANT', and `SET
     PASSWORD' generate long hashes unless the server was started with
     the `--old-passwords' option. That option forces the server to
     generate short password hashes instead.


The purpose of the `--old-passwords' option is to allow you to maintain
backward compatibility with pre-4.1 clients under circumstances where
the server would otherwise generate long password hashes. The option
doesn't affect authentication (4.1 clients can still use accounts that
have long password hashes), but it does prevent creation of a long
password hash in the `user' table as the result of a password-changing
operation. Were that to occur, the account no longer could be used by
pre-4.1 clients. Without the `--old-passwords' option, the following
undesirable scenario is possible:

   * An old client connects to an account that has a short password
     hash.

   * The client changes its own password. Without `--old-passwords',
     this results in the account having a long password hash.

   * The next time the old client attempts to connect to the account,
     it cannot, because the account now has a long password hash that
     requires the new hashing mechanism during authentication. (Once an
     account has a long password hash in the user table, only 4.1
     clients can authenticate for it, because pre-4.1 clients do not
     understand long hashes.)


This scenario illustrates that, if you must support older pre-4.1
clients, it is dangerous to run a 4.1 server without using the
`--old-passwords' option.  By running the server with
`--old-passwords', password-changing operations will not generate long
password hashes and thus do not cause accounts to become inaccessible
to older clients. (Those clients cannot inadvertently lock themselves
out by changing their password and ending up with a long password hash.)

The downside of the `--old-passwords' option is that any passwords you
create or change will use short hashes, even for 4.1 clients. Thus, you
lose the additional security provided by long password hashes. If you
want to create an account that has a long hash (for example, for use by
4.1 clients), you must do so while running the server without
`--old-passwords'.

The following scenarios are possible for running a 4.1 server:

*Scenario 1:* Short `Password' column in user table:

   * Only short hashes can be stored in the `Password' column.

   * The server uses only short hashes during client authentication.

   * For connected clients, password hash-generating operations
     involving `PASSWORD()', `GRANT', or `SET PASSWORD' use short hashes
     exclusively.  Any change to an account's password results in that
     account having a short password hash.

   * The `--old-passwords' option can be used but is superfluous because
     with a short `Password' column, the server will generate only short
     password hashes anyway.


*Scenario 2:* Long `Password' column; server not started with
`--old-passwords' option:

   * Short or long hashes can be stored in the `Password' column.

   * 4.1 clients can authenticate for accounts that have short or long
     hashes.

   * Pre-4.1 clients can authenticate only for accounts that have short
     hashes.

   * For connected clients, password hash-generating operations
     involving `PASSWORD()', `GRANT', or `SET PASSWORD' use long hashes
     exclusively.  A change to an account's password results in that
     account having a long password hash.


As indicated earlier, a danger in this scenario is that it is possible
for accounts that have a short password hash to become inaccessible to
pre-4.1 clients. A change to such an account's password made via
`GRANT', `PASSWORD()', or `SET PASSWORD' results in the account being
given a long password hash. From that point on, no pre-4.1 client can
authenticate to that account until the client upgrades to 4.1.

To deal with this problem, you can change a password in a special way.
For example, normally you use `SET PASSWORD' as follows to change an
account password:

     mysql> SET PASSWORD FOR 'SOME_USER'@'SOME_HOST' = PASSWORD('mypass');

To change the password but create a short hash, use the
`OLD_PASSWORD()' function instead:

     mysql> SET PASSWORD FOR 'SOME_USER'@'SOME_HOST' = OLD_PASSWORD('mypass');

`OLD_PASSWORD()' is useful for situations in which you explicitly want
to generate a short hash.

*Scenario 3:* Long `Password' column; server started with
`--old-passwords' option:

   * Short or long hashes can be stored in the `Password' column.

   * 4.1 clients can authenticate for accounts that have short or long
     hashes (but note that it is possible to create long hashes only
     when the server is started without `--old-passwords').

   * Pre-4.1 clients can authenticate only for accounts that have short
     hashes.

   * For connected clients, password hash-generating operations
     involving `PASSWORD()', `GRANT', or `SET PASSWORD' use short hashes
     exclusively.  Any change to an account's password results in that
     account having a short password hash.


In this scenario, you cannot create accounts that have long password
hashes, because the `--old-passwords' option prevents generation of
long hashes.  Also, if you create an account with a long hash before
using the `--old-passwords' option, changing the account's password
while `--old-passwords' is in effect results in the account being given
a short password, causing it to lose the security benefits of a longer
hash.

The disadvantages for these scenarios may be summarized as follows:

In scenario 1, you cannot take advantage of longer hashes that provide
more secure authentication.

In scenario 2, accounts with short hashes become inaccessible to pre-4.1
clients if you change their passwords without explicitly using
`OLD_PASSWORD()'.

In scenario 3, `--old-passwords' prevents accounts with short hashes
from becoming inaccessible, but password-changing operations cause
accounts with long hashes to revert to short hashes, and you cannot
change them back to long hashes while `--old-passwords' is in effect.

Implications of Password Hashing Changes for Application Programs
.................................................................

An upgrade to MySQL 4.1 can cause a compatibility issue for
applications that use `PASSWORD()' to generate passwords for their own
purposes. Applications really should not do this, because `PASSWORD()'
should be used only to manage passwords for MySQL accounts. But some
applications use `PASSWORD()' for their own purposes anyway.

If you upgrade to 4.1 and run the server under conditions where it
generates long password hashes, an application that uses `PASSWORD()'
for its own passwords will break.  The recommended course of action is
to modify the application to use another function, such as `SHA1()' or
`MD5()', to produce hashed values.  If that is not possible, you can
use the `OLD_PASSWORD()' function, which is provided to generate short
hashes in the old format. But note that `OLD_PASSWORD()' may one day no
longer be supported.

If the server is running under circumstances where it generates short
hashes, `OLD_PASSWORD()' is available but is equivalent to `PASSWORD()'.

Password Hashing in MySQL 4.1.0
...............................

Password hashing in MySQL 4.1.0 differs from hashing in 4.1.1 and up.
The 4.1.0 differences are:

   * Password hashes are 45 bytes long rather than 41 bytes.

   * The `PASSWORD()' function is non-repeatable.  That is, with a given
     argument X, successive calls to `PASSWORD(X)' generate different
     results.


These differences make authentication in 4.1.0 incompatible with that of
releases that follow it.  If you have upgraded to MySQL 4.1.0, it is
recommended that you upgrade to a newer version as soon as possible.
After you do, reassign any long passwords in the `user' table so that
they are compatible with the 41-byte format.

MySQL User Account Management
=============================

This section describes how to set up accounts for clients of your MySQL
server. It discusses the following topics:

   * The meaning of account names and passwords as used in MySQL and
     how that compares to names and passwords used by your operating
     system

   * How to set up new accounts and remove existing accounts

   * How to change passwords

   * Guidelines for using passwords securely

   * How to use secure connections with SSL


MySQL Usernames and Passwords
-----------------------------

A MySQL account is defined in terms of a username and the client host
or hosts from which the user can connect to the server. The account
also has a password.  There are several distinctions between the way
usernames and passwords are used by MySQL and the way they are used by
your operating system:

   * Usernames, as used by MySQL for authentication purposes, have
     nothing to do with usernames (login names) as used by Windows or
     Unix.  On Unix, most MySQL clients by default try to log in using
     the current Unix username as the MySQL username, but that is for
     convenience only. The default can be overridden easily, because
     client programs allow any username to be specified with a `-u' or
     `--user' option. Because this means that anyone can attempt to
     connect to the server using any username, you can't make a
     database secure in any way unless all MySQL accounts have
     passwords.  Anyone who specifies a username for an account that
     has no password will be able to connect successfully to the server.

   * MySQL usernames can be up to 16 characters long. Operating system
     usernames might have a different maximum length. For example, Unix
     usernames typically are limited to eight characters.

   * MySQL passwords have nothing to do with passwords for logging in
     to your operating system.  There is no necessary connection
     between the password you use to log in to a Windows or Unix
     machine and the password you use to access the MySQL server on
     that machine.

   * MySQL encrypts passwords using its own algorithm. This encryption
     is different from that used during the Unix login process.  MySQL
     password encryption is the same as that implemented by the
     `PASSWORD()' SQL function.  Unix password encryption is the same
     as that implemented by the `ENCRYPT()' SQL function.  See the
     descriptions of the `PASSWORD()' and `ENCRYPT()' functions in
     *Note Encryption functions::.  From version 4.1 on, MySQL employs
     a stronger authentication method that has better password
     protection during the connection process than in earlier versions.
     It is secure even if TCP/IP packets are sniffed or the `mysql'
     database is captured.  (In earlier versions, even though passwords
     are stored in encrypted form in the `user' table, knowledge of the
     encrypted password value could be used to connect to the MySQL
     server.)


When you install MySQL, the grant tables are populated with an initial
set of accounts. These accounts have names and access privileges that
are described in *Note Default privileges::, which also discusses how
to assign passwords to them.  Thereafter, you normally set up, modify,
and remove MySQL accounts using the `GRANT' and `REVOKE' statements.
*Note `GRANT': GRANT.

When you connect to a MySQL server with a command-line client, you
should specify the username and password for the account that you want
to use:

     shell> mysql --user=monty --password=GUESS DB_NAME

If you prefer short options, the command looks like this:

     shell> mysql -u monty -pGUESS DB_NAME

There must be _no space_ between the `-p' option and the following
password value.  *Note Connecting::.

The preceding commands include the password value on the command line,
which can be a security risk.  *Note Password security::.  To avoid
this, specify the `--password' or `-p' option without any following
password value:

     shell> mysql --user=monty --password DB_NAME
     shell> mysql -u monty -p DB_NAME

Then the client program will print a prompt and wait for you to enter
the password.  (In these examples, DB_NAME is _not_ interpreted as a
password, because it is separated from the preceding password option by
a space.)

On some systems, the library call that MySQL uses to prompt for a
password automatically limits the password to eight characters.  That
is a problem with the system library, not with MySQL.  Internally,
MySQL doesn't have any limit for the length of the password.  To work
around the problem, change your MySQL password to a value that is eight
or fewer characters long, or put your password in an option file.

Adding New User Accounts to MySQL
---------------------------------

You can create MySQL accounts in two ways:

   * By using `GRANT' statements

   * By manipulating the MySQL grant tables directly

The preferred method is to use `GRANT' statements, because they are
more concise and less error-prone. `GRANT' is available as of MySQL
3.22.11; its syntax is described in *Note `GRANT': GRANT.

Another option for creating accounts is to use one of several available
third-party programs that offer capabilities for MySQL account
administration.  `phpMyAdmin' is one such program.

The following examples show how to use the `mysql' client program to
set up new users.  These examples assume that privileges are set up
according to the defaults described in *Note Default privileges::.
This means that to make changes, you must connect to the MySQL server
as the MySQL `root' user, and the `root' account must have the `INSERT'
privilege for the `mysql' database and the `RELOAD' administrative
privilege.

First, use the `mysql' program to connect to the server as the MySQL
`root' user:

     shell> mysql --user=root mysql

If you have assigned a password to the `root' account, you'll also need
to supply a `--password' or `-p' option for this `mysql' command and
also for those later in this section.

After connecting to the server as `root', you can add new accounts.
The following statements use `GRANT' to set up four new accounts:

     mysql> GRANT ALL PRIVILEGES ON *.* TO 'monty'@'localhost'
         ->     IDENTIFIED BY 'some_pass' WITH GRANT OPTION;
     mysql> GRANT ALL PRIVILEGES ON *.* TO 'monty'@'%'
         ->     IDENTIFIED BY 'some_pass' WITH GRANT OPTION;
     mysql> GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost';
     mysql> GRANT USAGE ON *.* TO 'dummy'@'localhost';

The accounts created by these `GRANT' statements have the following
properties:

   * Two of the accounts have a username of `monty' and a password of
     `some_pass'. Both accounts are superuser accounts with full
     privileges to do anything. One account (`'monty'@'localhost'') can
     be used only when connecting from the local host. The other
     (`'monty'@'%'') can be used to connect from any other host.  Note
     that it is necessary to have both accounts for `monty' to be able
     to connect from anywhere as `monty'.  Without the `localhost'
     account, the anonymous-user account for `localhost' that is
     created by `mysql_install_db' would take precedence when `monty'
     connects from the local host. As a result, `monty' would be
     treated as an anonymous user.  The reason for this is that the
     anonymous-user account has a more specific `Host' column value
     than the `'monty'@'%'' account and thus comes earlier in the
     `user' table sort order.  (`user' table sorting is discussed in
     *Note Connection access::.)

   * One account has a username of `admin' and no password.  This
     account can be used only by connecting from the local host.  It is
     granted the `RELOAD' and `PROCESS' administrative privileges.
     These privileges allow the `admin' user to execute the `mysqladmin
     reload', `mysqladmin refresh', and `mysqladmin flush-XXX' commands,
     as well as `mysqladmin processlist' .  No privileges are granted
     for accessing any databases. You could add such privileges later
     by issuing additional `GRANT' statements.

   * One account has a username of `dummy' and no password.  This
     account can be used only by connecting from the local host.  No
     privileges are granted. The `USAGE' privilege in the `GRANT'
     statement allows you to create an account without giving it any
     privileges. It has the effect of setting all the global privileges
     to `'N''.  It is assumed that you will grant specific privileges
     to the account later.


As an alternative to `GRANT', you can create the same accounts directly
by issuing `INSERT' statements and then telling the server to reload
the grant tables:

     shell> mysql --user=root mysql
     mysql> INSERT INTO user
         ->     VALUES('localhost','monty',PASSWORD('some_pass'),
         ->     'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');
     mysql> INSERT INTO user
         ->     VALUES('%','monty',PASSWORD('some_pass'),
         ->     'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');
     mysql> INSERT INTO user SET Host='localhost',User='admin',
         ->     Reload_priv='Y', Process_priv='Y';
     mysql> INSERT INTO user (Host,User,Password)
         ->     VALUES('localhost','dummy','');
     mysql> FLUSH PRIVILEGES;

The reason for using `FLUSH PRIVILEGES' when you create accounts with
`INSERT' is to tell the server to re-read the grant tables.  Otherwise,
the changes will go unnoticed until you restart the server. With
`GRANT', `FLUSH PRIVILEGES' is unnecessary.

The reason for using the `PASSWORD()' function with `INSERT' is to
encrypt the password. The `GRANT' statement encrypts the password for
you, so `PASSWORD()' is unnecessary.

The `'Y'' values enable privileges for the accounts.  Depending on your
MySQL version, you may have to use a different number of `'Y'' values
in the first two `INSERT' statements. (Versions prior to 3.22.11 have
fewer privilege columns, and versions from 4.0.2 on have more.)  For the
`admin' account, the more readable extended `INSERT' syntax using `SET'
that is available starting with MySQL 3.22.11 is used.

In the `INSERT' statement for the `dummy' account, only the `Host',
`User', and `Password' columns in the `user' table record are assigned
values. None of the privilege columns are set explicitly, so MySQL
assigns them all the default value of `'N''.  This is equivalent to
what `GRANT USAGE' does.

Note that to set up a superuser account, it is necessary only to create
a `user' table entry with the privilege columns set to `'Y''.  `user'
table privileges are global, so no entries in any of the other grant
tables are needed.

The next examples create three accounts and give them access to specific
databases. Each of them has a username of `custom' and password of
`obscure'.

To create the accounts with `GRANT', use the following statements:

     shell> mysql --user=root mysql
     mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
         ->     ON bankaccount.*
         ->     TO 'custom'@'localhost'
         ->     IDENTIFIED BY 'obscure';
     mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
         ->     ON expenses.*
         ->     TO 'custom'@'whitehouse.gov'
         ->     IDENTIFIED BY 'obscure';
     mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
         ->     ON customer.*
         ->     TO 'custom'@'server.domain'
         ->     IDENTIFIED BY 'obscure';

The three accounts can be used as follows:

   * The first account can access the `bankaccount' database, but only
     from the local host.

   * The second account can access the `expenses' database, but only
     from the host `whitehouse.gov'.

   * The third account can access the `customer' database, but only
     from the host `server.domain'.

To set up the `custom' accounts without `GRANT', use `INSERT'
statements as follows to modify the grant tables directly:

     shell> mysql --user=root mysql
     mysql> INSERT INTO user (Host,User,Password)
         ->     VALUES('localhost','custom',PASSWORD('obscure'));
     mysql> INSERT INTO user (Host,User,Password)
         ->     VALUES('whitehouse.gov','custom',PASSWORD('obscure'));
     mysql> INSERT INTO user (Host,User,Password)
         ->     VALUES('server.domain','custom',PASSWORD('obscure'));
     mysql> INSERT INTO db
         ->     (Host,Db,User,Select_priv,Insert_priv,
         ->     Update_priv,Delete_priv,Create_priv,Drop_priv)
         ->     VALUES('localhost','bankaccount','custom',
         ->     'Y','Y','Y','Y','Y','Y');
     mysql> INSERT INTO db
         ->     (Host,Db,User,Select_priv,Insert_priv,
         ->     Update_priv,Delete_priv,Create_priv,Drop_priv)
         ->     VALUES('whitehouse.gov','expenses','custom',
         ->     'Y','Y','Y','Y','Y','Y');
     mysql> INSERT INTO db
         ->     (Host,Db,User,Select_priv,Insert_priv,
         ->     Update_priv,Delete_priv,Create_priv,Drop_priv)
         ->     VALUES('server.domain','customer','custom',
         ->     'Y','Y','Y','Y','Y','Y');
     mysql> FLUSH PRIVILEGES;

The first three `INSERT' statements add `user' table entries that allow
the user `custom' to connect from the various hosts with the given
password, but grant no global privileges (all privileges are set to the
default value of `'N'').  The next three `INSERT' statements add `db'
table entries that grant privileges to `custom' for the `bankaccount',
`expenses', and `customer' databases, but only when accessed from the
proper hosts.  As usual when you modify the grant tables directly, you
tell the server to reload them with `FLUSH PRIVILEGES' so that the
privilege changes take effect.

If you want to give a specific user access from all machines in a given
domain (for example, `mydomain.com'), you can issue a `GRANT' statement
that uses the `%' wildcard character in the host part of the account
name:

     mysql> GRANT ...
         ->     ON *.*
         ->     TO 'myname'@'%.mydomain.com'
         ->     IDENTIFIED BY 'mypass';

To do the same thing by modifying the grant tables directly, do this:

     mysql> INSERT INTO user (Host,User,Password,...)
         ->     VALUES('%.mydomain.com','myname',PASSWORD('mypass'),...);
     mysql> FLUSH PRIVILEGES;

Removing User Accounts from MySQL
---------------------------------

To remove an account, use the `DROP USER' statement, which was added in
MySQL 4.1.1.  For older versions of MySQL, use `DELETE' instead.  The
account removal procedure is described in *Note Drop user::.

Limiting Account Resources
--------------------------

Before MySQL 4.0.2, the only available method for limiting use of MySQL
server resources is to set the `max_user_connections' system variable
to a non-zero value. But that method is strictly global.  It does not
allow for management of individual accounts. Also, it limits only the
number of simultaneous connections made using a single account, not
what a client can do once connected. Both types of control are interest
to many MySQL administrators, particularly those for Internet Service
Providers.

Starting from MySQL 4.0.2, you can limit the following server resources
for individual accounts:

   * The number of queries that an account can issue per hour

   * The number of updates that an account can issue per hour

   * The number of times an account can connect to the server per hour

Any statement that a client can issue counts against the query limit.
Only statements that modify databases or tables count against the update
limit.

An account in this context is a single record in the `user' table. Each
account is uniquely identified by its `User' and `Host' column values.

As a prerequisite for using this feature, the `user' table in the
`mysql' database must contain the resource-related columns.  Resource
limits are stored in the `max_questions', `max_updates', and
`max_connections' columns.  If your `user' table doesn't have these
columns, it must be upgraded; see *Note Upgrading-grant-tables::.

To set resource limits with a `GRANT' statement, use a `WITH' clause
that names each resource to be limited and a per-hour count indicating
the limit value.  For example, to create a new account that can access
the `customer' database, but only in a limited fashion, issue this
statement:

     mysql> GRANT ALL ON customer.* TO 'francis'@'localhost'
         ->     IDENTIFIED BY 'frank'
         ->     WITH MAX_QUERIES_PER_HOUR 20
         ->          MAX_UPDATES_PER_HOUR 10
         ->          MAX_CONNECTIONS_PER_HOUR 5;

The limit types need not all be named in the `WITH' clause, but those
named can be present in any order. The value for each limit should be an
integer representing a count per hour. If the `GRANT' statement has no
`WITH' clause, the limits are each set to the default value of zero
(that is, no limit).

To set or change limits for an existing account, use a `GRANT USAGE'
statement at the global level (`ON *.*'). The following statement
changes the query limit for `francis' to 100:

     mysql> GRANT USAGE ON *.* TO 'francis'@'localhost'
         ->     WITH MAX_QUERIES_PER_HOUR 100;

This statement leaves the account's existing privileges unchanged and
modifies only the limit values specified.

To remove an existing limit, set its value to zero. For example, to
remove the limit on how many times per hour `francis' can connect, use
this statement:

     mysql> GRANT USAGE ON *.* TO 'francis'@'localhost'
         ->     WITH MAX_CONNECTIONS_PER_HOUR 0;

Resource-use counting takes place when any account has a non-zero limit
placed on its use of any of the resources.

As the server runs, it counts the number of times each account uses
resources.  If an account reaches its limit on number of connections
within the last hour, further connections for the account are rejected
until that hour is up. Similarly, if the account reaches its limit on
the number of queries or updates, further queries or updates are
rejected until the hour is up. In all such cases, an appropriate error
message is issued.

Resource counting is done per account, not per client. For example, if
your account has a query limit of 50, you cannot increase your limit to
100 by making two simultaneous client connections to the server.
Queries issued on both connections are counted together.

The current resource-use counts can be reset globally for all accounts,
or individually for a given count:

   * To reset the current counts to zero for all accounts, issue a
     `FLUSH USER_RESOURCES' statement. The counts also can be reset by
     reloading the grant tables (for example, with a `FLUSH PRIVILEGES'
     statement or a `mysqladmin reload' command).

   * The counts for an individual account can be set to zero by
     re-granting it any of its limits. To do this, use `GRANT USAGE' as
     described earlier and specify a limit value equal to the value
     that the account already has.


Assigning Account Passwords
---------------------------

Passwords may be assigned from the command line by using the
`mysqladmin' command:

     shell> mysqladmin -u USER_NAME -h HOST_NAME password "NEWPWD"

The account for which this command resets the password is the one with a
`user' table record that matches USER_NAME in the `User' column and the
client host _from which you connect_ in the `Host' column.

Another way to assign a password to an account is to issue a `SET
PASSWORD' statement:

     mysql> SET PASSWORD FOR 'jeffrey'@'%' = PASSWORD('biscuit');

Only users such as `root' with update access to the `mysql' database
can change the password for other users.  If you are not connected as
an anonymous user, you can change your own password by omitting the
`FOR' clause:

     mysql> SET PASSWORD = PASSWORD('biscuit');

You can also use a `GRANT USAGE' statement at the global level (`ON
*.*') to assign a password to an account without affecting the
account's current privileges:

     mysql> GRANT USAGE ON *.* TO 'jeffrey'@'%' IDENTIFIED BY 'biscuit';

Although it is generally preferable to assign passwords using one of the
preceding methods, you can also do so by modifying the `user' table
directly:

   * To establish a password when creating a new account, provide a
     value for the `Password' column:

          shell> mysql -u root mysql
          mysql> INSERT INTO user (Host,User,Password)
              -> VALUES('%','jeffrey',PASSWORD('biscuit'));
          mysql> FLUSH PRIVILEGES;

   * To change the password for an existing account, use `UPDATE' to
     set the `Password' column value:

          shell> mysql -u root mysql
          mysql> UPDATE user SET Password = PASSWORD('bagel')
              -> WHERE Host = '%' AND User = 'francis';
          mysql> FLUSH PRIVILEGES;


When you assign an account a password using `SET PASSWORD', `INSERT',
or `UPDATE', you must use the `PASSWORD()' function to encrypt it.
(The only exception is that you need not use `PASSWORD()' if the
password is empty.) `PASSWORD()' is necessary because the `user' table
stores passwords in encrypted form, not as plaintext.  If you forget
that fact, you are likely to set passwords like this:

     shell> mysql -u root mysql
     mysql> INSERT INTO user (Host,User,Password)
         -> VALUES('%','jeffrey','biscuit');
     mysql> FLUSH PRIVILEGES;

The result is that the literal value `'biscuit'' is stored as the
password in the `user' table, not the encrypted value.  When `jeffrey'
attempts to connect to the server using this password, the value is
encrypted and compared to the value stored in the `user' table.
However, the stored value is the literal string `'biscuit'', so the
comparison fails and the server rejects the connection:

     shell> mysql -u jeffrey -pbiscuit test
     Access denied

If you set passwords using the `GRANT ... IDENTIFIED BY' statement or
the `mysqladmin password' command, they both take care of encrypting
the password for you.  The `PASSWORD()' function is unnecessary.

*Note*: `PASSWORD()' encryption is different from Unix password
encryption.  *Note User names::.

Keeping Your Password Secure
----------------------------

On an administrative level, you should never grant access to the
`mysql.user' table to any non-administrative accounts. Passwords in the
`user' table are stored in encrypted form, but in versions of MySQL
earlier than 4.1, knowing the encrypted password for an account makes it
possible to connect to the server using that account.

When you run a client program to connect to the MySQL server, it is
inadvisable to specify your password in a way that exposes it to
discovery by other users.  The methods you can use to specify your
password when you run client programs are listed here, along with an
assessment of the risks of each method:

   * Use a `-pYOUR_PASS' or `--password=YOUR_PASS' option on the command
     line.  For example:

          shell> mysql -u francis -pfrank DB_NAME

     This is convenient but insecure, because your password becomes
     visible to system status programs such as `ps' that may be invoked
     by other users to display command lines.  MySQL clients typically
     overwrite the command-line password argument with zeros during
     their initialization sequence, but there is still a brief interval
     during which the value is visible.

   * Use a `-p' or `--password' option with no password value
     specified.  In this case, the client program solicits the password
     from the terminal:

          shell> mysql -u francis -p DB_NAME
          Enter password: ********

     The `*' characters indicate where you enter your password. The
     password is not displayed as you enter it.

     It is more secure to enter your password this way than to specify
     it on the command line because it is not visible to other users.
     However, this method of entering a password is suitable only for
     programs that you run interactively.  If you want to invoke a
     client from a script that runs non-interactively, there is no
     opportunity to enter the password from the terminal. On some
     systems, you may even find that the first line of your script is
     read and interpreted (incorrectly) as your password!

   * Store your password in an option file.  For example, on Unix you
     can list your password in the `[client]' section of the `.my.cnf'
     file in your home directory:

          [client]
          password=your_pass

     If you store your password in `.my.cnf', the file should not be
     accessible to anyone but yourself. To ensure this, set the file
     access mode to `400' or `600'. For example:

          shell> chmod 600 .my.cnf

     *Note Option files:: discusses option files in more detail.

   * Store your password in the `MYSQL_PWD' environment variable.  This
     method of specifying your MySQL password must be considered
     extremely insecure and should not be used.  Some versions of `ps'
     include an option to display the environment of running processes.
     If you set `MYSQL_PWD', your password will be exposed to any other
     user who runs `ps'.  Even on systems without such a version of
     `ps', it is unwise to assume that there are no other methods by
     which users can examine process environments.  *Note Environment
     variables::.


All in all, the safest methods are to have the client program prompt
for the password or to specify the password in a properly protected
option file.

Using Secure Connections
------------------------

Beginning with version 4.0.0, MySQL has support for secure (encrypted)
connections between MySQL clients and the server using the Secure
Sockets Layer (SSL) protocol.  This section discusses how to use SSL
connections.  It also describes a way to set up SSH on Windows.

The standard configuration of MySQL is intended to be as fast as
possible, so encrypted connections are not used by default.  Doing so
would make the client/server protocol much slower.  Encrypting data is
a CPU-intensive operation that requires the computer to do additional
work and can delay other MySQL tasks.  For applications that require
the security provided by encrypted connections, the extra computation
is warranted.

MySQL allows encryption to be enabled on a per-connection basis. You can
choose a normal unencrypted connection or a secure encrypted SSL
connection according the requirements of individual applications.

Basic SSL Concepts
..................

To understand how MySQL uses SSL, it's necessary to explain some basic
SSL and X509 concepts. People who are already familiar with them can
skip this part.

By default, MySQL uses unencrypted connections between the client and
the server. This means that someone with access to the network could
watch all your traffic and look at the data being sent or received.
They could even change the data while it is in transit between client
and server. To improve security a little, you can compress
client/server traffic by using the `--compress' option when invoking
client programs.  However, this will not foil a determined attacker.

When you need to move information over a network in a secure fashion,
an unencrypted connection is unacceptable.  Encryption is the way to
make any kind of data unreadable. In fact, today's practice requires
many additional security elements from encryption algorithms.  They
should resist many kind of known attacks such as changing the order of
encrypted messages or replaying data twice.

SSL is a protocol that uses different encryption algorithms to ensure
that data received over a public network can be trusted. It has
mechanisms to detect any data change, loss, or replay. SSL also
incorporates algorithms that provide identity verification using the
X509 standard.

X509 makes it possible to identify someone on the Internet.  It is most
commonly used in e-commerce applications. In basic terms, there should
be some company called a "Certificate Authority" (or CA) that assigns
electronic certificates to anyone who needs them. Certificates rely on
asymmetric encryption algorithms that have two encryption keys (a
public key and a secret key). A certificate owner can show the
certificate to another party as proof of identity. A certificate
consists of its owner's public key. Any data encrypted with this public
key can be decrypted only using the corresponding secret key, which is
held by the owner of the certificate.

If you need more information about SSL, X509, or encryption, use your
favorite Internet search engine to search for keywords in which you are
interested.

Requirements
............

To use SSL connections between the MySQL server and client programs,
your system must be able to support OpenSSL and your version of MySQL
must be 4.0.0 or newer.

To get secure connections to work with MySQL, you must do the following:

  1. Install the OpenSSL library. We have tested MySQL with OpenSSL
     0.9.6.  If you need OpenSSL, visit `http://www.openssl.org'.

  2. When you configure MySQL, run the `configure' script with the
     `--with-vio' and `--with-openssl' options.

  3. Make sure that you have upgraded your grant tables to include the
     SSL-related columns in the `mysql.user' table.  This is necessary
     if your grant tables date from a version prior to MySQL 4.0.0.
     The upgrade procedure is described in *Note
     Upgrading-grant-tables::.

  4. To check whether a running `mysqld' server supports OpenSSL,
     examine the value of the `have_openssl' system variable:

          mysql> SHOW VARIABLES LIKE 'have_openssl';
          +---------------+-------+
          | Variable_name | Value |
          +---------------+-------+
          | have_openssl  | YES   |
          +---------------+-------+

     If the value is `YES', the server supports OpenSSL connections.

Setting Up SSL Certificates for MySQL
.....................................

Here is an example for setting up SSL certificates for MySQL:

     DIR=`pwd`/openssl
     PRIV=$DIR/private

     mkdir $DIR $PRIV $DIR/newcerts
     cp /usr/share/ssl/openssl.cnf $DIR
     replace ./demoCA $DIR -- $DIR/openssl.cnf

     # Create necessary files: $database, $serial and $new_certs_dir
     # directory (optional)

     touch $DIR/index.txt
     echo "01" > $DIR/serial

     #
     # Generation of Certificate Authority(CA)
     #

     openssl req -new -x509 -keyout $PRIV/cakey.pem -out $DIR/cacert.pem \
         -config $DIR/openssl.cnf

     # Sample output:
     # Using configuration from /home/monty/openssl/openssl.cnf
     # Generating a 1024 bit RSA private key
     # ................++++++
     # .........++++++
     # writing new private key to '/home/monty/openssl/private/cakey.pem'
     # Enter PEM pass phrase:
     # Verifying password - Enter PEM pass phrase:
     # -----
     # You are about to be asked to enter information that will be
     # incorporated into your certificate request.
     # What you are about to enter is what is called a Distinguished Name
     # or a DN.
     # There are quite a few fields but you can leave some blank
     # For some fields there will be a default value,
     # If you enter '.', the field will be left blank.
     # -----
     # Country Name (2 letter code) [AU]:FI
     # State or Province Name (full name) [Some-State]:.
     # Locality Name (eg, city) []:
     # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
     # Organizational Unit Name (eg, section) []:
     # Common Name (eg, YOUR name) []:MySQL admin
     # Email Address []:

     #
     # Create server request and key
     #
     openssl req -new -keyout $DIR/server-key.pem -out \
         $DIR/server-req.pem -days 3600 -config $DIR/openssl.cnf

     # Sample output:
     # Using configuration from /home/monty/openssl/openssl.cnf
     # Generating a 1024 bit RSA private key
     # ..++++++
     # ..........++++++
     # writing new private key to '/home/monty/openssl/server-key.pem'
     # Enter PEM pass phrase:
     # Verifying password - Enter PEM pass phrase:
     # -----
     # You are about to be asked to enter information that will be
     # incorporated into your certificate request.
     # What you are about to enter is what is called a Distinguished Name
     # or a DN.
     # There are quite a few fields but you can leave some blank
     # For some fields there will be a default value,
     # If you enter '.', the field will be left blank.
     # -----
     # Country Name (2 letter code) [AU]:FI
     # State or Province Name (full name) [Some-State]:.
     # Locality Name (eg, city) []:
     # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
     # Organizational Unit Name (eg, section) []:
     # Common Name (eg, YOUR name) []:MySQL server
     # Email Address []:
     #
     # Please enter the following 'extra' attributes
     # to be sent with your certificate request
     # A challenge password []:
     # An optional company name []:

     #
     # Remove the passphrase from the key (optional)
     #

     openssl rsa -in $DIR/server-key.pem -out $DIR/server-key.pem

     #
     # Sign server cert
     #
     openssl ca  -policy policy_anything -out $DIR/server-cert.pem \
         -config $DIR/openssl.cnf -infiles $DIR/server-req.pem

     # Sample output:
     # Using configuration from /home/monty/openssl/openssl.cnf
     # Enter PEM pass phrase:
     # Check that the request matches the signature
     # Signature ok
     # The Subjects Distinguished Name is as follows
     # countryName           :PRINTABLE:'FI'
     # organizationName      :PRINTABLE:'MySQL AB'
     # commonName            :PRINTABLE:'MySQL admin'
     # Certificate is to be certified until Sep 13 14:22:46 2003 GMT
     # (365 days)
     # Sign the certificate? [y/n]:y
     #
     #
     # 1 out of 1 certificate requests certified, commit? [y/n]y
     # Write out database with 1 new entries
     # Data Base Updated

     #
     # Create client request and key
     #
     openssl req -new -keyout $DIR/client-key.pem -out \
         $DIR/client-req.pem -days 3600 -config $DIR/openssl.cnf

     # Sample output:
     # Using configuration from /home/monty/openssl/openssl.cnf
     # Generating a 1024 bit RSA private key
     # .....................................++++++
     # .............................................++++++
     # writing new private key to '/home/monty/openssl/client-key.pem'
     # Enter PEM pass phrase:
     # Verifying password - Enter PEM pass phrase:
     # -----
     # You are about to be asked to enter information that will be
     # incorporated into your certificate request.
     # What you are about to enter is what is called a Distinguished Name
     # or a DN.
     # There are quite a few fields but you can leave some blank
     # For some fields there will be a default value,
     # If you enter '.', the field will be left blank.
     # -----
     # Country Name (2 letter code) [AU]:FI
     # State or Province Name (full name) [Some-State]:.
     # Locality Name (eg, city) []:
     # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
     # Organizational Unit Name (eg, section) []:
     # Common Name (eg, YOUR name) []:MySQL user
     # Email Address []:
     #
     # Please enter the following 'extra' attributes
     # to be sent with your certificate request
     # A challenge password []:
     # An optional company name []:

     #
     # Remove a passphrase from the key (optional)
     #
     openssl rsa -in $DIR/client-key.pem -out $DIR/client-key.pem

     #
     # Sign client cert
     #

     openssl ca  -policy policy_anything -out $DIR/client-cert.pem \
         -config $DIR/openssl.cnf -infiles $DIR/client-req.pem

     # Sample output:
     # Using configuration from /home/monty/openssl/openssl.cnf
     # Enter PEM pass phrase:
     # Check that the request matches the signature
     # Signature ok
     # The Subjects Distinguished Name is as follows
     # countryName           :PRINTABLE:'FI'
     # organizationName      :PRINTABLE:'MySQL AB'
     # commonName            :PRINTABLE:'MySQL user'
     # Certificate is to be certified until Sep 13 16:45:17 2003 GMT
     # (365 days)
     # Sign the certificate? [y/n]:y
     #
     #
     # 1 out of 1 certificate requests certified, commit? [y/n]y
     # Write out database with 1 new entries
     # Data Base Updated

     #
     # Create a my.cnf file that you can use to test the certificates
     #

     cnf=""
     cnf="$cnf [client]"
     cnf="$cnf ssl-ca=$DIR/cacert.pem"
     cnf="$cnf ssl-cert=$DIR/client-cert.pem"
     cnf="$cnf ssl-key=$DIR/client-key.pem"
     cnf="$cnf [mysqld]"
     cnf="$cnf ssl-ca=$DIR/cacert.pem"
     cnf="$cnf ssl-cert=$DIR/server-cert.pem"
     cnf="$cnf ssl-key=$DIR/server-key.pem"
     echo $cnf | replace " " '
     ' > $DIR/my.cnf

To test SSL connections, start the server as follows, where `$DIR' is
the pathname to the directory where the sample `my.cnf' option file is
located:

     shell> mysqld --defaults-file=$DIR/my.cnf &

Then invoke a client program using the same option file:

     shell> mysql --defaults-file=$DIR/my.cnf

If you have a MySQL source distribution, you can also test your setup by
modifying the preceding `my.cnf' file to refer to the demonstration
certificate and key files in the `SSL' directory of the distribution.

SSL `GRANT' Options
...................

MySQL can check X509 certificate attributes in addition to the usual
authentication that is based on the username and password.  To specify
SSL-related options for a MySQL account, use the `REQUIRE' clause of
the `GRANT' statement.  *Note `GRANT': GRANT.

There are different possibilities for limiting connection types for an
account:

   * If an account has no SSL or X509 requirements, unencrypted
     connections are allowed if the username and password are valid.
     However, encrypted connections also can be used at the client's
     option, if the client has the proper certificate and key files.

   * `REQUIRE SSL' option limits the server to allow only SSL encrypted
     connections for the account. Note that this option can be omitted
     if there are any ACL records that allow non-SSL connections.

          mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
              -> IDENTIFIED BY 'goodsecret' REQUIRE SSL;

   * `REQUIRE X509' means that the client must have a valid certificate
     but that the exact certificate, issuer, and subject do not matter.
     The only requirement is that it should be possible to verify its
     signature with one of the CA certificates.

          mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
              -> IDENTIFIED BY 'goodsecret' REQUIRE X509;

   * `REQUIRE ISSUER 'issuer'' places the restriction on connection
     attempts that the client must present a valid X509 certificate
     issued by CA `'issuer''.  If the client presents a certificate
     that is valid but has a different issuer, the server rejects the
     connection.  Use of X509 certificates always implies encryption,
     so the `SSL' option is unneccessary.

          mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
              -> IDENTIFIED BY 'goodsecret'
              -> REQUIRE ISSUER '/C=FI/ST=Some-State/L=Helsinki/
                 O=MySQL Finland AB/CN=Tonu Samuel/Email=[e-mail]';

     Note that the `ISSUER' value should be entered as a single string.

   * `REQUIRE SUBJECT 'subject'' places the restriction on connection
     attempts that the client must present a valid X509 certificate
     with subject `'subject'' on it.  If the client presents a
     certificate that is valid but has a different subject, the server
     rejects the connection.

          mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
              -> IDENTIFIED BY 'goodsecret'
              -> REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/
                 O=MySQL demo client certificate/
                 CN=Tonu Samuel/Email=[e-mail]';

     Note that the `SUBJECT' value should be entered as a single string.

   * `REQUIRE CIPHER 'cipher'' is needed to ensure that strong enough
     ciphers and key lengths will be used. SSL itself can be weak if
     old algorithms with short encryption keys are used. Using this
     option, we can ask for some exact cipher method to allow a
     connection.

          mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
              -> IDENTIFIED BY 'goodsecret'
              -> REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA';


The `SUBJECT', `ISSUER', and `CIPHER' options can be combined in the
`REQUIRE' clause like this:

     mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
         -> IDENTIFIED BY 'goodsecret'
         -> REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/
            O=MySQL demo client certificate/
            CN=Tonu Samuel/Email=[e-mail]'
         -> AND ISSUER '/C=FI/ST=Some-State/L=Helsinki/
            O=MySQL Finland AB/CN=Tonu Samuel/Email=[e-mail]'
         -> AND CIPHER 'EDH-RSA-DES-CBC3-SHA';

Note that the `SUBJECT' and `ISSUER' values each should be entered as a
single string.

Starting from MySQL 4.0.4, the `AND' keyword is optional between
`REQUIRE' options.

The order of the options does not matter, but no option can be specified
twice.

SSL Command-Line Options
........................

The following list describes options that are used for specifying the
use of SSL, certificate files, and key files.  These options are
available beginning with MySQL 4.0. They may be given on the command
line or in an option file.

`--ssl'
     For the server, this option specifies that the server allows SSL
     connections.  For a client program, it allows the client to
     connect to the server using SSL.  This option is not sufficient in
     itself to cause an SSL connection to be used.  You must also
     specify the `--ssl-ca', `--ssl-cert', and `--ssl-key' options.

     This option is more often used in its opposite form to indicate
     that SSL should _not_ be used. To do this, specify the option as
     `--skip-ssl' or `--ssl=0'.

     Note that use of `--ssl' doesn't _require_ an SSL connection.  For
     example, if the server or client is compiled without SSL support,
     a normal unencrypted connection will be used.

     The secure way to ensure that an SSL connection will be used is to
     create an account on the server that includes a `REQUIRE SSL'
     clause in the `GRANT' statement.  Then use this account to connect
     to the server, with both a server and client that have SSL support
     enabled.

`--ssl-ca=FILE_NAME'
     The path to a file with a list of trusted SSL CAs.

`--ssl-capath=DIRECTORY_NAME'
     The path to a directory that contains trusted SSL CA certificates
     in pem format.

`--ssl-cert=FILE_NAME'
     The name of the SSL certificate file to use for establishing a
     secure connection.

`--ssl-cipher=CIPHER_LIST'
     A list of allowable ciphers to use for SSL encryption.
     CIPHER_LIST has the same format as the `openssl ciphers' command.

     Example: `--ssl-cipher=ALL:-AES:-EXP'

`--ssl-key=FILE_NAME'
     The name of the SSL key file to use for establishing a secure
     connection.

Connecting to MySQL Remotely from Windows with SSH
..................................................

Here is a note about how to connect to get a secure connection to remote
MySQL server with SSH (by David Carlson <[e-mail]>):

  1. Install an SSH client on your Windows machine.  As a user, the
     best non-free one I've found is from `SecureCRT' from
     `http://www.vandyke.com/'.  Another option is `f-secure' from
     `http://www.f-secure.com/'. You can also find some free ones on
     `Google' at
     `http://directory.google.com/Top/Computers/Security/Products_and_Tools/Cryptography/SSH/Clients/Windows/'.

  2. Start your Windows SSH client.  Set `Host_Name =
     yourmysqlserver_URL_or_IP'.  Set `userid=your_userid' to log in to
     your server. This `userid' value may not be the same as the
     username of your MySQL account.

  3. Set up port forwarding. Either do a remote forward (Set
     `local_port: 3306', `remote_host: yourmysqlservername_or_ip',
     `remote_port: 3306' ) or a local forward (Set `port: 3306',
     `host: localhost', `remote port: 3306').

  4. Save everything, otherwise you'll have to redo it the next time.

  5. Log in to your server with the SSH session you just created.

  6. On your Windows machine, start some ODBC application (such as
     Access).

  7. Create a new file in Windows and link to MySQL using the ODBC
     driver the same way you normally do, except type in `localhost'
     for the MySQL host server, not `yourmysqlservername'.

You should now have an ODBC connection to MySQL, encrypted using SSH.

Disaster Prevention and Recovery
================================

This section discusses how to make database backups and how to perform
table maintenance.  The syntax of the SQL statements described here is
given in *Note Database Administration::.  Much of the information here
pertains primarily to `MyISAM' tables.  `InnoDB' backup procedures are
given in *Note Backing up::.

Database Backups
----------------

Because MySQL tables are stored as files, it is easy to do a backup. To
get a consistent backup, do a `LOCK TABLES' on the relevant tables,
followed by `FLUSH TABLES' for the tables.  See *Note `LOCK TABLES':
LOCK TABLES and *Note `FLUSH': FLUSH.  You need only a read lock; this
allows other clients to continue to query the tables while you are
making a copy of the files in the database directory.  The `FLUSH
TABLES' statement is needed to ensure that the all active index pages
are written to disk before you start the backup.

If you want to make an SQL-level backup of a table, you can use `SELECT
INTO ... OUTFILE' or `BACKUP TABLE'.  For `SELECT INTO ... OUTFILE',
the output file cannot already exist.  For `BACKUP TABLE', the same is
true as of MySQL 3.23.56 and 4.0.12, because this would be a security
risk.  See *Note `SELECT': SELECT and *Note `BACKUP TABLE': BACKUP
TABLE.

Another way to back up a database is to use the `mysqldump' program or
the `mysqlhotcopy script'.  See *Note `mysqldump': mysqldump and *Note
`mysqlhotcopy': mysqlhotcopy.

  1. Do a full backup of your database:

          shell> mysqldump --tab=/PATH/TO/SOME/DIR --opt DB_NAME

     Or:

          shell> mysqlhotcopy DB_NAME /PATH/TO/SOME/DIR

     You can also simply copy all table files (`*.frm', `*.MYD', and
     `*.MYI' files) as long as the server isn't updating anything.  The
     `mysqlhotcopy' script uses this method.  (But note that these
     methods will not work if your database contains `InnoDB' tables.
     `InnoDB' does not store table contents in database directories,
     and `mysqlhotcopy' works only for `MyISAM' and `ISAM' tables.)

  2. Stop `mysqld' if it's running, then start it with the
     `--log-bin[=file_name]' option.  *Note Binary log::. The binary
     log files provide you with the information you need to replicate
     changes to the database that are made subsequent to the point at
     which you executed `mysqldump'.

If your MySQL server is a slave replication server, then regardless of
the backup method you choose, you should also back up the `master.info'
and `relay-log.info' files when you back up your slave's data. These
files are always needed to resume replication after you restore the
slave's data. If your slave is subject to replicating `LOAD DATA
INFILE' commands, you should also back up any `SQL_LOAD-*' files that
may exist in the directory specified by the `--slave-load-tmpdir'
option. (This location defaults to the value of the `tmpdir' variable
if not specified.) The slave needs these files to resume replication of
any interrupted `LOAD DATA INFILE' operations.

If you have to restore `MyISAM' tables, try to recover them using
`REPAIR TABLE' or `myisamchk -r' first.  That should work in 99.9% of
all cases.  If `myisamchk' fails, try the following procedure.  Note
that it will work only if you have enabled binary logging by starting
MySQL with the `--log-bin' option; see *Note Binary log::.

  1. Restore the original `mysqldump' backup, or binary backup.

  2. Execute the following command to re-run the updates in the binary
     logs:

          shell> mysqlbinlog hostname-bin.[0-9]* | mysql

     In your case, you may want to re-run only certain binary logs, from
     certain positions (usually you want to re-run all binary logs from
     the date of the restored backup, excepting possibly some incorrect
     queries).  See *Note `mysqlbinlog': mysqlbinlog for more
     information on the `mysqlbinlog' utility and how to use it.

     If you are using the update logs instead, you can process their
     contents like this:

          shell> ls -1 -t -r hostname.[0-9]* | xargs cat | mysql

     `ls' is used to sort the update log filenames into the right order.


You can also do selective backups of individual files:

   * To dump the table, use `SELECT * INTO OUTFILE 'FILE_NAME' FROM
     TBL_NAME'.

   * To reload the table, use and restore with `LOAD DATA INFILE
     'file_name' REPLACE ...' To avoid duplicate records, the table
     must have a `PRIMARY KEY' or a `UNIQUE' index. The `REPLACE'
     keyword causes old records to be replaced with new ones when a new
     record duplicates an old record on a unique key value.


If you have performance problems with your server while making backups,
one strategy that can help is to set up replication and perform backups
on the slave rather than on the master.  *Note Replication Intro::.

If you are using a Veritas filesystem, you can make a backup like this:

  1. From a client program, execute `FLUSH TABLES WITH READ LOCK'.

  2. From another shell, execute `mount vxfs snapshot'.

  3. From the first client, execute `UNLOCK TABLES'.

  4. Copy files from the snapshot.

  5. Unmount the snapshot.

Table Maintenance and Crash Recovery
------------------------------------

The following text discusses how to use `myisamchk' to check or repair
`MyISAM' tables (tables with `.MYI' and `.MYD' files).  The same
concepts apply to using `isamchk' to check or repair `ISAM' tables
(tables with `.ISM' and `.ISD' files).  *Note Storage engines::.

You can use the `myisamchk' utility to get information about your
database tables or to check, repair, or optimize them.  The following
sections describe how to invoke `myisamchk' (including a description of
its options), how to set up a table maintenance schedule, and how to
use `myisamchk' to perform its various functions.

Even though table repair with `myisamchk' is quite secure, it's always
a good idea to make a backup _before_ doing a repair (or any
maintenance operation that could make a lot of changes to a table)

`myisamchk' operations that affect indexes can cause `FULLTEXT' indexes
to be rebuilt with full-text parameters that are incompatible with the
values used by the MySQL server. To avoid this, read the instructions in
*Note `myisamchk' general options: myisamchk general options.

In many cases, you may find it simpler to do `MyISAM' table maintenance
using the SQL statements that perform operations that `myisamchk' can
do:

   * To check or repair `MyISAM' tables, use `CHECK TABLE' or `REPAIR
     TABLE'.

   * To optimize `MyISAM' tables, use `OPTIMIZE TABLE'.

   * To analyze `MyISAM' tables, use `ANALYZE TABLE'.


These statements were introduced in different versions, but all are
available from MySQL 3.23.14 on.  See *Note `ANALYZE TABLE': ANALYZE
TABLE, *Note `CHECK TABLE': CHECK TABLE, *Note `OPTIMIZE TABLE':
OPTIMIZE TABLE, and *Note `REPAIR TABLE': REPAIR TABLE.  The statements
can be used directly, or by means of the `mysqlcheck' client program,
which provides a command-line interface to them.

One advantage of these statements over `myisamchk' is that the server
does all the work. With `myisamchk', you must make sure that the server
does not use the tables at the same time. Otherwise, there can be
unwanted interaction betweeen `myisamchk' and the server.

`myisamchk' Invocation Syntax
.............................

Invoke `myisamchk' like this:

     shell> myisamchk [OPTIONS] TBL_NAME

The OPTIONS specify what you want `myisamchk' to do.  They are
described in the following sections.  You can also get a list of
options by invoking `myisamchk --help'.

With no options, `myisamchk' simply checks your table as the default
operation.  To get more information or to tell `myisamchk' to take
corrective action, specify options as described in the following
discussion.

TBL_NAME is the database table you want to check or repair.  If you run
`myisamchk' somewhere other than in the database directory, you must
specify the path to the database directory, because `myisamchk' has no
idea where the database is located.  In fact, `myisamchk' doesn't
actually care whether the files you are working on are located in a
database directory. You can copy the files that correspond to a
database table into some other location and perform recovery operations
on them there.

You can name several tables on the `myisamchk' command line if you
wish.  You can also specify a table by naming its index file (the file
with the `.MYI' suffix). This allows you to specify all tables in a
directory by using the pattern `*.MYI'.  For example, if you are in a
database directory, you can check all the `MyISAM' tables in that
directory like this:

     shell> myisamchk *.MYI

If you are not in the database directory, you can check all the tables
there by specifying the path to the directory:

     shell> myisamchk /path/to/database_dir/*.MYI

You can even check all tables in all databases by specifying a wildcard
with the path to the MySQL data directory:

     shell> myisamchk /path/to/datadir/*/*.MYI

The recommended way to quickly check all `MyISAM' and `ISAM' tables is:

     shell> myisamchk --silent --fast /path/to/datadir/*/*.MYI
     shell> isamchk --silent /path/to/datadir/*/*.ISM

If you want to check all `MyISAM' and `ISAM' tables and repair any that
are corrupted, you can use the following commands:

     shell> myisamchk --silent --force --fast --update-state \
               -O key_buffer=64M -O sort_buffer=64M \
               -O read_buffer=1M -O write_buffer=1M \
               /path/to/datadir/*/*.MYI
     shell> isamchk --silent --force -O key_buffer=64M \
               -O sort_buffer=64M -O read_buffer=1M -O write_buffer=1M \
               /path/to/datadir/*/*.ISM

These commands assume that you have more than 64MB free.  For more
information about memory allocation with `myisamchk', see *Note
myisamchk memory::.

You must ensure that no other program is using the tables while you are
running `myisamchk'.  Otherwise, when you run `myisamchk', it may
display the following error message:

     warning: clients are using or haven't closed the table properly

This means that you are trying to check a table that has been updated by
another program (such as the `mysqld' server) that hasn't yet closed
the file or that has died without closing the file properly.

If `mysqld' is running, you must force it to flush any table
modifications that are still buffered in memory by using `FLUSH
TABLES'. You should then ensure that no one is using the tables while
you are running `myisamchk'.  The easiest way to avoid this problem is
to use `CHECK TABLE' instead of `myisamchk' to check tables.

General Options for `myisamchk'
...............................

The options described in this section can be used for any type of table
maintenance operation performed by `myisamchk'.  The sections following
this one describe options that pertain only to specific operations,
such as table checking or repairing.

`--help, -?'
     Display a help message and exit.

`--debug=DEBUG_OPTIONS, -# DEBUG_OPTIONS'
     Write a debugging log. The DEBUG_OPTIONS string often is
     `'d:t:o,FILE_NAME''.

`--silent, -s'
     Silent mode.  Write output only when errors occur. You can use `-s'
     twice (`-ss') to make `myisamchk' very silent.

`--verbose, -v'
     Verbose mode.  Print more information. This can be used with `-d'
     and `-e'. Use `-v' multiple times (`-vv', `-vvv') for even more
     output.

`--version, -V'
     Display version information and exit.

`--wait, -w'
     Instead of terminating with an error if the table is locked, wait
     until the table is unlocked before continuing.  Note that if you
     are running `mysqld' with the `--skip-external-locking' option,
     the table can be locked only by another `myisamchk' command.

You can also set the following variables by using `--VAR_NAME=VALUE'
options:

*Variable*                *Default Value*
`decode_bits'             9
`ft_max_word_len'         version-dependent
`ft_min_word_len'         4
`ft_stopword_file'        built-in list
`key_buffer_size'         523264
`myisam_block_size'       1024
`read_buffer_size'        262136
`sort_buffer_size'        2097144
`sort_key_blocks'         16
`write_buffer_size'       262136

It is also possible to set variables by using
`--set-variable=VAR_NAME=VALUE' or `-O VAR_NAME=VALUE' syntax. However,
this syntax is deprecated as of MySQL 4.0.

The possible `myisamchk' variables and their default values can be
examined with `myisamchk --help':

`sort_buffer_size' is used when the keys are repaired by sorting keys,
which is the normal case when you use `--recover'.

`key_buffer_size' is used when you are checking the table with
`--extend-check' or when the keys are repaired by inserting keys row by
row into the table (like when doing normal inserts). Repairing through
the key buffer is used in the following cases:

   * You use `--safe-recover'.

   * The temporary files needed to sort the keys would be more than
     twice as big as when creating the key file directly.  This is
     often the case when you have large key values for  `CHAR',
     `VARCHAR', or `TEXT' columns, because the sort operation needs to
     store the complete key values as it proceeds. If you have lots of
     temporary space and you can force `myisamchk' to repair by
     sorting, you can use the `--sort-recover' option.


Repairing through the key buffer takes much less disk space than using
sorting, but is also much slower.

If you want a faster repair, set the `key_buffer_size' and
`sort_buffer_size' variables to about 25% of your available memory.
You can set both variables to large values, because only one of them is
used at a time.

`myisam_block_size' is the size used for index blocks. It is available
as of MySQL 4.0.0.

The `ft_min_word_len' and `ft_max_word_len' variables are available as
of MySQL 4.0.0.  `ft_stopword_file' is available as of MySQL 4.0.19.

`ft_min_word_len' and `ft_max_word_len' indicate the minimum and
maximum word length for `FULLTEXT' indexes. `ft_stopword_file' names
the stopword file. These need to be set under the following
circumstances.

If you use `myisamchk' to perform an operation that modifies table
indexes (such as repair or analyze), the `FULLTEXT' indexes are rebuilt
using the default full-text parameter values for minimum and maximum
word length and the stopword file unless you specify otherwise.  This
can result in queries failing.

The problem occurs because these parameters are known only by the
server.  They are not stored in `MyISAM' index files.  To avoid the
problem if you have modified the minimum or maximum word length or the
stopword file in the server, specify the same `ft_min_word_len',
`ft_max_word_len', and `ft_stopword_file' values to `myisamchk' that
you use for `mysqld'. For example, if you have set the minimum word
length to 3, you can repair a table with `myisamchk' like this:

     shell> myisamchk --recover --ft_min_word_len=3 TBL_NAME.MYI

To ensure that `myisamchk' and the server use the same values for
full-text parameters, you can place each one in both the `[mysqld]' and
`[myisamchk]' sections of an option file:

     [mysqld]
     ft_min_word_len=3

     [myisamchk]
     ft_min_word_len=3

An alternative to using `myisamchk' is to use the `REPAIR TABLE',
`ANALYZE TABLE', `OPTIMIZE TABLE', or `ALTER TABLE'.  These statements
are performed by the server, which knows the proper full-text parameter
values to use.

Check Options for `myisamchk'
.............................

`myisamchk' supports the following options for table checking
operations:

`--check, -c'
     Check the table for errors. This is the default operation if you
     specify no option that selects an operation type explicitly.

`--check-only-changed, -C'
     Check only tables that have changed since the last check.

`--extend-check, -e'
     Check the table very thoroughly. This is quite slow if the table
     has many indexes.  This option should only be used in extreme
     cases.  Normally, `myisamchk' or `myisamchk --medium-check' should
     be able to determine whether there are any errors in the table.

     If you are using `--extend-check' and have plenty of memory,
     setting the `key_buffer_size' variable to a large value will help
     the repair operation run faster.

`--fast, -F'
     Check only tables that haven't been closed properly.

`--force, -f'
     Do a repair operation automatically if `myisamchk' finds any
     errors in the table.  The repair type is the same as that
     specified with the `--repair' or `-r' option.

`--information, -i'
     Print informational statistics about the table that is checked.

`--medium-check, -m'
     Do a check that is faster than an `--extend-check' operation.
     This finds only 99.99% of all errors, which should be good enough
     in most cases.

`--read-only, -T'
     Don't mark the table as checked. This is useful if you use
     `myisamchk' to check a table that is in use by some other
     application that doesn't use locking, such as `mysqld' when run
     with the `--skip-external-locking' option.

`--update-state, -U'
     Store information in the `.MYI' file to indicate when the table was
     checked and whether the table crashed.  This should be used to get
     full benefit of the `--check-only-changed' option, but you
     shouldn't use this option if the `mysqld' server is using the
     table and you are running it with the `--skip-external-locking'
     option.

Repair Options for `myisamchk'
..............................

`myisamchk' supports the following options for table repair operations:

`--backup, -B'
     Make a backup of the `.MYD' file as `file_name-time.BAK'

`--character-sets-dir=PATH'
     The directory where character sets are installed.  *Note Character
     sets::.

`--correct-checksum'
     Correct the checksum information for the table.

`--data-file-length=#, -D #'
     Maximum length of the data file (when re-creating data file when
     it's "full").

`--extend-check, -e'
     Do a repair that tries to to recover every possible row from the
     data file.  Normally this will also find a lot of garbage rows.
     Don't use this option unless you are totally desperate.

`--force, -f'
     Overwrite old temporary files (files with names like
     `TBL_NAME.TMD') instead of aborting.

`--keys-used=#, -k #'
     For `myisamchk', the option value indicates which indexes to
     update.  Each binary bit of the option value corresponds to a
     table index, where the first index is bit 0.  For `isamchk', the
     option value indicates that only the first # of the table indexes
     should be updated.  In either case, an option value of 0 disables
     updates to all indexes, which can be used to get faster inserts.
     Deactivated indexes can be reactivated by using `myisamchk -r' or
     (`isamchk -r').

`--no-symlinks, -l'
     Do not follow symbolic links. Normally `myisamchk' repairs the
     table that a symlink points to.  This option doesn't exist as of
     MySQL 4.0, because versions from 4.0 on will not remove symlinks
     during repair operations.

`--parallel-recover, -p'
     Uses the same technique as `-r' and `-n', but creates all the keys
     in parallel, using different threads.  This option was added in
     MySQL 4.0.2.  _This is alpha code. Use at your own risk!_

`--quick, -q'
     Achieve a faster repair by not modifying the data file. You can
     specify this option twice to force `myisamchk' to modify the
     original data file in case of duplicate keys.

`--recover, -r'
     Do a repair that can fix almost any problem except unique keys
     that aren't unique (which is an extremely unlikely error with
     `ISAM'/`MyISAM' tables).  If you want to recover a table, this is
     the option to try first. You should try `-o' only if `myisamchk'
     reports that the table can't be recovered by `-r'.  (In the
     unlikely case that `-r' fails, the data file is still intact.)

     If you have lots of memory, you should increase the value of
     `sort_buffer_size'.

`--safe-recover, -o'
     Do a repair using an old recovery method that reads through all
     rows in order and updates all index trees based on the rows found.
     This is an order of magnitude slower than `-r', but can handle a
     couple of very unlikely cases that `-r' cannot.  This recovery
     method also uses much less disk space than `-r'. Normally, you
     should repair first with `-r', and then with `-o' only if `-r'
     fails.

     If you have lots of memory, you should increase the value of
     `key_buffer_size'.

`--set-character-set=NAME'
     Change the character set used by the table indexes.

`--sort-recover, -n'
     Force `myisamchk' to use sorting to resolve the keys even if the
     temporary files should be very big.

`--tmpdir=PATH, -t PATH'
     Path of the directory to be used for storing temporary files. If
     this is not set, `myisamchk' uses the value of the `TMPDIR'
     environment variable.  Starting from MySQL 4.1, `tmpdir' can be
     set to a list of directory paths that will be used successively in
     round-robin fashion for creating temporary files. The separator
     character between directory names should be colon (`:') on Unix
     and semicolon (`;') on Windows, NetWare, and OS/2.

`--unpack, -u'
     Unpack a table that was packed with `myisampack'.

Other Options for `myisamchk'
.............................

`myisamchk' supports the following options for actions other than table
checks and repairs:

`--analyze, -a'
     Analyze the distribution of keys. This improves join performance
     by enabling the join optimizer to better choose the order in which
     to join the tables and which keys it should use. To obtain
     information about the distribution, use a `myisamchk --description
     --verbose TBL_NAME' command or the `SHOW KEYS FROM TBL_NAME'
     statement.

`--description, -d'
     Print some descriptive information about the table.

`--set-auto-increment[=VALUE], -A[VALUE]'
     Force `AUTO_INCREMENT' numbering for new records to start at the
     given value (or higher, if there are already records with
     `AUTO_INCREMENT' values this large). If VALUE is not specified,
     `AUTO_INCREMENT' number for new records begins with the largest
     value currently in the table, plus one.

`--sort-index, -S'
     Sort the index tree blocks in high-low order.  This optimizes
     seeks and makes table scanning by key faster.

`--sort-records=#, -R #'
     Sort records according to a particular index.  This makes your
     data much more localized and may speed up range-based `SELECT' and
     `ORDER BY' operations that use this index. (The first time you use
     this option to sort a table, it may be very slow.) To determine a
     table's index numbers, use `SHOW KEYS', which displays a table's
     indexes in the same order that `myisamchk' sees them.  Indexes are
     numbered beginning with 1.

`myisamchk' Memory Usage
........................

Memory allocation is important when you run `myisamchk'.  `myisamchk'
uses no more memory than you specify with the `-O' options.  If you are
going to use `myisamchk' on very large tables, you should first decide
how much memory you want it to use.  The default is to use only about
3MB to perform repairs.  By using larger values, you can get
`myisamchk' to operate faster.  For example, if you have more than 32MB
RAM, you could use options such as these (in addition to any other
options you might specify):

     shell> myisamchk -O sort=16M -O key=16M -O read=1M -O write=1M ...

Using `-O sort=16M' should probably be enough for most cases.

Be aware that `myisamchk' uses temporary files in `TMPDIR'. If `TMPDIR'
points to a memory filesystem, you may easily get out of memory errors.
If this happens, set `TMPDIR' to point at some directory located on a
filesystem with more space and run `myisamchk' again.

When repairing, `myisamchk' will also need a lot of disk space:

   * Double the size of the data file (the original one and a copy).
     This space is not needed if you do a repair with `--quick'; in this
     case, only the index file is re-created.  This space is needed on
     the same filesystem as the original data file! (The copy is
     created in the same directory as the original.)

   * Space for the new index file that replaces the old one. The old
     index file is truncated at the start of the repair operation, so
     you usually ignore this space.  This space is needed on the same
     filesystem as the original index file!

   * When using `--recover' or `--sort-recover' (but not when using
     `--safe-recover'), you will need space for a sort buffer. The
     amount of space required is:

          (LARGEST_KEY + ROW_POINTER_LENGTH) * NUMBER_OF_ROWS * 2

     You can check the length of the keys and the `row_pointer_length'
     with `myisamchk -dv TBL_NAME'.  This space is allocated in the
     temporary directory (specified by `TMPDIR' or `--tmpdir=PATH').


If you have a problem with disk space during repair, you can try to use
`--safe-recover' instead of `--recover'.

Using `myisamchk' for Crash Recovery
....................................

If you run `mysqld' with `--skip-external-locking' (which is the
default on some systems, such as Linux), you can't reliably use
`myisamchk' to check a table when `mysqld' is using the same table.  If
you can be sure that no one is accessing the tables through `mysqld'
while you run `myisamchk', you only have to do `mysqladmin
flush-tables' before you start checking the tables.  If you can't
guarantee this, then you must stop `mysqld' while you check the tables.
If you run `myisamchk' while `mysqld' is updating the tables, you may
get a warning that a table is corrupt even when it isn't.

If you are not using `--skip-external-locking', you can use `myisamchk'
to check tables at any time.  While you do this, all clients that try
to update the table will wait until `myisamchk' is ready before
continuing.

If you use `myisamchk' to repair or optimize tables, you _must_ always
ensure that the `mysqld' server is not using the table (this also
applies if you are using `--skip-external-locking').  If you don't take
down `mysqld', you should at least do a `mysqladmin flush-tables'
before you run `myisamchk'.  Your tables _may become corrupted_ if the
server and `myisamchk' access the tables simultaneously.

This section describes how to check for and deal with data corruption
in MySQL databases.  If your tables get corrupted frequently you should
try to find the reason why.  *Note Crashing::.

The `MyISAM' table section contains reason for why a table could be
corrupted. *Note `MyISAM' table problems: MyISAM table problems.

When performing crash recovery, it is important to understand that each
`MyISAM' table TBL_NAME in a database corresponds to three files in the
database directory:

*File*         *Purpose*
`TBL_NAME.frm' Definition (format) file
`TBL_NAME.MYD' Data file
`TBL_NAME.MYI' Index file

Each of these three file types is subject to corruption in various
ways, but problems occur most often in data files and index files.

`myisamchk' works by creating a copy of the `.MYD' data file row by
row. It ends the repair stage by removing the old `.MYD' file and
renaming the new file to the original file name.  If you use `--quick',
`myisamchk' does not create a temporary `.MYD' file, but instead
assumes that the `.MYD' file is correct and only generates a new index
file without touching the `.MYD' file. This is safe, because
`myisamchk' automatically detects whether the `.MYD' file is corrupt
and aborts the repair if it is.  You can also specify the `--quick'
option twice to `myisamchk'.  In this case, `myisamchk' does not abort
on some errors (such as duplicate-key errors) but instead tries to
resolve them by modifying the `.MYD' file. Normally the use of two
`--quick' options is useful only if you have too little free disk space
to perform a normal repair.  In this case, you should at least make a
backup before running `myisamchk'.

How to Check `MyISAM' Tables for Errors
.......................................

To check a `MyISAM' table, use the following commands:

`myisamchk TBL_NAME'
     This finds 99.99% of all errors. What it can't find is corruption
     that involves _only_ the data file (which is very unusual). If you
     want to check a table, you should normally run `myisamchk' without
     options or with either the `-s' or `--silent' option.

`myisamchk -m TBL_NAME'
     This finds 99.999% of all errors. It first checks all index
     entries for errors and then reads through all rows. It calculates
     a checksum for all keys in the rows and verifies that the checksum
     matches the checksum for the keys in the index tree.

`myisamchk -e TBL_NAME'
     This does a complete and thorough check of all data (`-e' means
     "extended check"). It does a check-read of every key for each row
     to verify that they indeed point to the correct row.  This may
     take a long time for a large table that has many indexes.
     Normally, `myisamchk' stops after the first error it finds. If you
     want to obtain more information, you can add the `--verbose'
     (`-v') option.  This causes `myisamchk' to keep going, up through
     a maximum of 20 errors.

`myisamchk -e -i TBL_NAME'
     Like the previous command, but the `-i' option tells `myisamchk' to
     print some informational statistics, too.

In most cases, a simple `myisamchk' with no arguments other than the
table name is sufficient to check a table.

How to Repair Tables
....................

The discussion in this section describes how to use `myisamchk' on
`MyISAM' tables (extensions `.MYI' and `.MYD').  If you are using
`ISAM' tables (extensions `.ISM' and `.ISD'), you should use `isamchk'
instead; the concepts are similar.

If you are using MySQL 3.23.16 and above, you can (and should) use the
`CHECK TABLE' and `REPAIR TABLE' statements to check and repair
`MyISAM' tables.  See *Note `CHECK TABLE': CHECK TABLE and *Note
`REPAIR TABLE': REPAIR TABLE.

The symptoms of a corrupted table include queries that abort
unexpectedly and observable errors such as these:

   * `TBL_NAME.frm' is locked against change

   * Can't find file `TBL_NAME.MYI' (Errcode: ###)

   * Unexpected end of file

   * Record file is crashed

   * Got error ### from table handler

To get more information about the error you can run `perror' ###, where
### is the error number. The following example shows how to use
`perror' to find the meanings for the most common error numbers that
indicate a problem with a table:

     shell> perror 126 127 132 134 135 136 141 144 145
     126 = Index file is crashed / Wrong file format
     127 = Record-file is crashed
     132 = Old database file
     134 = Record was already deleted (or record file crashed)
     135 = No more room in record file
     136 = No more room in index file
     141 = Duplicate unique key or constraint on write or update
     144 = Table is crashed and last repair failed
     145 = Table was marked as crashed and should be repaired

Note that error 135 (no more room in record file) and error 136 (no more
room in index file) are not errors that can be fixed by a simple
repair. In this case, you have to use `ALTER TABLE' to increase the
`MAX_ROWS' and `AVG_ROW_LENGTH' table option values:

     ALTER TABLE TBL_NAME MAX_ROWS=XXX AVG_ROW_LENGTH=YYY;

If you don't know the current table option values, use `SHOW CREATE
TABLE tbl_name'.

For the other errors, you must repair your tables. `myisamchk' can
usually detect and fix most problems that occur.

The repair process involves up to four stages, described here. Before
you begin, you should change location to the database directory and
check the permissions of the table files. On Unix, make sure that they
are readable by the user that `mysqld' runs as (and to you, because you
need to access the files you are checking).  If it turns out you need
to modify files, they must also be writable by you.

The options that you can use for table maintenance with `myisamchk' and
`isamchk' are described in several of the earlier subsections of *Note
Table maintenance::.

The following section is for the cases where the above command fails or
if you want to use the extended features that `myisamchk' and `isamchk'
provide.

If you are going to repair a table from the command line, you must first
stop the `mysqld' server. Note that when you do `mysqladmin shutdown'
on a remote server, the `mysqld' server will still be alive for a while
after `mysqladmin' returns, until all queries are stopped and all keys
have been flushed to disk.

*Stage 1: Checking your tables*

Run `myisamchk *.MYI' or `myisamchk -e *.MYI' if you have more time.
Use the `-s' (silent) option to suppress unnecessary information.

If the `mysqld' server is down, you should use the `--update-state'
option to tell `myisamchk' to mark the table as 'checked'.

You have to repair only those tables for which `myisamchk' announces an
error.  For such tables, proceed to Stage 2.

If you get weird errors when checking (such as `out of memory' errors),
or if `myisamchk' crashes, go to Stage 3.

*Stage 2: Easy safe repair*

Note: If you want a repair operation to go much faster, you should set
the values of the `sort_buffer_size' and `key_buffer_size' variables
each to about 25% of your available memory when running `myisamchk' or
`isamchk'.

First, try `myisamchk -r -q TBL_NAME' (`-r -q' means "quick recovery
mode"). This will attempt to repair the index file without touching the
data file.  If the data file contains everything that it should and the
delete links point at the correct locations within the data file, this
should work, and the table is fixed. Start repairing the next table.
Otherwise, use the following procedure:

  1. Make a backup of the data file before continuing.

  2. Use `myisamchk -r TBL_NAME' (`-r' means "recovery mode"). This will
     remove incorrect records and deleted records from the data file and
     reconstruct the index file.

  3. If the preceding step fails, use `myisamchk --safe-recover
     TBL_NAME'.  Safe recovery mode uses an old recovery method that
     handles a few cases that regular recovery mode doesn't (but is
     slower).

If you get weird errors when repairing (such as `out of memory'
errors), or if `myisamchk' crashes, go to Stage 3.

*Stage 3: Difficult repair*

You should reach this stage only if the first 16KB block in the index
file is destroyed or contains incorrect information, or if the index
file is missing.  In this case, it's necessary to create a new index
file. Do so as follows:

  1. Move the data file to some safe place.

  2. Use the table description file to create new (empty) data and
     index files:

          shell> mysql DB_NAME
          mysql> SET AUTOCOMMIT=1;
          mysql> TRUNCATE TABLE TBL_NAME;
          mysql> quit

     If your version of MySQL doesn't have `TRUNCATE TABLE', use
     `DELETE FROM TBL_NAME' instead.

  3. Copy the old data file back onto the newly created data file.
     (Don't just move the old file back onto the new file; you want to
     retain a copy in case something goes wrong.)

Go back to Stage 2.  `myisamchk -r -q' should work now.  (This shouldn't
be an endless loop.)

As of MySQL 4.0.2, you can also use `REPAIR TABLE TBL_NAME USE_FRM',
which performs the whole procedure automatically.

*Stage 4: Very difficult repair*

You should reach this stage only if the `.frm' description file has also
crashed. That should never happen, because the description file isn't
changed after the table is created:

  1. Restore the description file from a backup and go back to Stage 3.
     You can also restore the index file and go back to Stage 2.  In
     the latter case, you should start with `myisamchk -r'.

  2. If you don't have a backup but know exactly how the table was
     created, create a copy of the table in another database.  Remove
     the new data file, then move the `.frm' description and `.MYI'
     index files from the other database to your crashed database.
     This gives you new description and index files, but leaves the
     `.MYD' data file alone.  Go back to Stage 2 and attempt to
     reconstruct the index file.


Table Optimization
..................

To coalesce fragmented records and eliminate wasted space resulting from
deleting or updating records, run `myisamchk' in recovery mode:

     shell> myisamchk -r TBL_NAME

You can optimize a table in the same way by using the SQL `OPTIMIZE
TABLE' statement.  `OPTIMIZE TABLE' does a repair of the table and a key
analysis, and also sorts the index tree to give faster key lookups.
There is also no possibility of unwanted interaction between a utility
and the server, because the server does all the work when you use
`OPTIMIZE TABLE'. *Note `OPTIMIZE TABLE': OPTIMIZE TABLE.

`myisamchk' also has a number of other options you can use to improve
the performance of a table:

   * `-S', `--sort-index'

   * `-R INDEX_NUM', `--sort-records=INDEX_NUM'

   * `-a', `--analyze'

For a full description of the options, see *Note myisamchk syntax::.

Setting Up a Table Maintenance Schedule
---------------------------------------

It is a good idea to perform table checks on a regular basis rather than
waiting for problems to occur.  One way to check and repair `MyISAM'
tables is with the `CHECK TABLE' and `REPAIR TABLE' statements.  These
are available starting with MySQL 3.23.16.  See *Note `CHECK TABLE':
CHECK TABLE and *Note `REPAIR TABLE': REPAIR TABLE.

Another way to check tables is to use `myisamchk'.  For maintenance
purposes, you can use `myisamchk -s'.  The `-s' option (short for
`--silent') causes `myisamchk' to run in silent mode, printing messages
only when errors occur.

It's also a good idea to check tables when the server starts.  For
example, whenever the machine has done a restart in the middle of an
update, you usually need to check all the tables that could have been
affected. (These are "expected crashed tables.")  To check `MyISAM'
tables automatically, start the server with the `--myisam-recover'
option, available as of MySQL 3.23.25.  If your server is too old to
support this option, you could add a test to `mysqld_safe' that runs
`myisamchk' to check all tables that have been modified during the last
24 hours if there is an old `.pid' (process ID) file left after a
restart.  (The `.pid' file is created by `mysqld' when it starts and
removed when it terminates normally.  The presence of a `.pid' file at
system startup time indicates that `mysqld' terminated abnormally.)

An even better test would be to check any table whose last-modified time
is more recent than that of the `.pid' file.

You should also check your tables regularly during normal system
operation.  At MySQL AB, we run a `cron' job to check all our important
tables once a week, using a line like this in a `crontab' file:

     35 0 * * 0 /path/to/myisamchk --fast --silent /path/to/datadir/*/*.MYI

This prints out information about crashed tables so that we can examine
and repair them when needed.

Because we haven't had any unexpectedly crashed tables (tables that
become corrupted for reasons other than hardware trouble) for a couple
of years now (this is really true), once a week is more than enough for
us.

We recommend that to start with, you execute `myisamchk -s' each night
on all tables that have been updated during the last 24 hours, until
you come to trust MySQL as much as we do.

Normally, MySQL tables need little maintenance.  If you are changing
`MyISAM' tables with dynamic-sized rows (tables with `VARCHAR', `BLOB',
or `TEXT' columns) or have tables with many deleted rows you may want
to defragment/reclaim space from the tables from time to time (once a
month?).

You can do this by using `OPTIMIZE TABLE' on the tables in question.
Or, if you can stop the `mysqld' server for a while, change location
into the data directory and use this command while the server is
stopped:

     shell> myisamchk -r -s --sort-index -O sort_buffer_size=16M */*.MYI

For `ISAM' tables, the command is similar:

     shell> isamchk -r -s --sort-index -O sort_buffer_size=16M */*.ISM

Getting Information About a Table
---------------------------------

To obtain a description of a table or statistics about it, use the
commands shown here. We explain some of the information in more detail
later:

   * `myisamchk -d TBL_NAME'

     Runs `myisamchk' in "describe mode" to produce a description of
     your table. If you start the MySQL server using the
     `--skip-external-locking' option, `myisamchk' may report an error
     for a table that is updated while it runs.  However, because
     `myisamchk' doesn't change the table in describe mode, there is no
     risk of destroying data.

   * `myisamchk -d -v TBL_NAME'

     Adding `-v' runs `myisamchk' in verbose mode so that it produces
     more information about what it is doing.

   * `myisamchk -eis TBL_NAME'

     Shows only the most important information from a table. This
     operation is slow because it must read the entire table.

   * `myisamchk -eiv TBL_NAME'

     This is like `-eis', but tells you what is being done.


Sample output for some of these commands follows. They are based on a
table with these data and index file sizes:

     -rw-rw-r--   1 monty    tcx     317235748 Jan 12 17:30 company.MYD
     -rw-rw-r--   1 davida   tcx      96482304 Jan 12 18:35 company.MYM

Example of `myisamchk -d' output:

     MyISAM file:     company.MYI
     Record format:   Fixed length
     Data records:    1403698  Deleted blocks:         0
     Recordlength:    226

     table description:
     Key Start Len Index   Type
     1   2     8   unique  double
     2   15    10  multip. text packed stripped
     3   219   8   multip. double
     4   63    10  multip. text packed stripped
     5   167   2   multip. unsigned short
     6   177   4   multip. unsigned long
     7   155   4   multip. text
     8   138   4   multip. unsigned long
     9   177   4   multip. unsigned long
         193   1           text

Example of `myisamchk -d -v' output:

     MyISAM file:         company
     Record format:       Fixed length
     File-version:        1
     Creation time:       1999-10-30 12:12:51
     Recover time:        1999-10-31 19:13:01
     Status:              checked
     Data records:            1403698  Deleted blocks:              0
     Datafile parts:          1403698  Deleted data:                0
     Datafile pointer (bytes):      3  Keyfile pointer (bytes):     3
     Max datafile length:  3791650815  Max keyfile length: 4294967294
     Recordlength:                226

     table description:
     Key Start Len Index   Type                  Rec/key     Root Blocksize
     1   2     8   unique  double                      1 15845376      1024
     2   15    10  multip. text packed stripped        2 25062400      1024
     3   219   8   multip. double                     73 40907776      1024
     4   63    10  multip. text packed stripped        5 48097280      1024
     5   167   2   multip. unsigned short           4840 55200768      1024
     6   177   4   multip. unsigned long            1346 65145856      1024
     7   155   4   multip. text                     4995 75090944      1024
     8   138   4   multip. unsigned long              87 85036032      1024
     9   177   4   multip. unsigned long             178 96481280      1024
         193   1           text

Example of `myisamchk -eis' output:

     Checking MyISAM file: company
     Key:  1:  Keyblocks used:  97%  Packed:    0%  Max levels:  4
     Key:  2:  Keyblocks used:  98%  Packed:   50%  Max levels:  4
     Key:  3:  Keyblocks used:  97%  Packed:    0%  Max levels:  4
     Key:  4:  Keyblocks used:  99%  Packed:   60%  Max levels:  3
     Key:  5:  Keyblocks used:  99%  Packed:    0%  Max levels:  3
     Key:  6:  Keyblocks used:  99%  Packed:    0%  Max levels:  3
     Key:  7:  Keyblocks used:  99%  Packed:    0%  Max levels:  3
     Key:  8:  Keyblocks used:  99%  Packed:    0%  Max levels:  3
     Key:  9:  Keyblocks used:  98%  Packed:    0%  Max levels:  4
     Total:    Keyblocks used:  98%  Packed:   17%

     Records:          1403698    M.recordlength:     226
     Packed:             0%
     Recordspace used:     100%   Empty space:          0%
     Blocks/Record:   1.00
     Record blocks:    1403698    Delete blocks:        0
     Recorddata:     317235748    Deleted data:         0
     Lost space:             0    Linkdata:             0

     User time 1626.51, System